Códigos de erro
A API usa códigos HTTP padrão. Estes são os que a superfície pública pode devolver.
| Código | Significado |
|---|---|
401 | API key ausente, malformada, inválida, revogada ou expirada. |
402 | Saldo de créditos insuficiente. |
403 | A chave não tem o scope exigido. |
404 | Recurso não encontrado (ou de outro tenant: não se distingue). |
409 | Conflito: o SKU já existe · lote não cancelável · operação com esse Idempotency-Key em andamento. |
413 | O corpo excede o limite de 2 MB (importação de catálogo e envio de imagens). |
415 | O arquivo enviado não é o que o `presign` declarou: a assinatura binária não corresponde ao `mime` (ou é um formato não aceito, como SVG). O objeto é descartado; comece de novo com o arquivo correto. |
422 | Payload inválido (incl. lote vazio ou com mais de 500 produtos) · Idempotency-Key reusada com outro payload ou endpoint. |
428 | Falta o Idempotency-Key obrigatório (POST /v1/batches). |
429 | Limite de taxa (tente após Retry-After) ou teto de gasto diário de IA (sem Retry-After). |
502 | O provedor de imagens rejeitou a solicitação (sessões de fotos com IA): não houve cobrança. Revise as referências e tente de novo. |
503 | Serviço em pausa (manutenção, IA desligada ou API pública desabilitada): nada foi cobrado. |