Erros
Formato
Todo erro tem o mesmo formato, em JSON ou XML conforme o formato escolhido:
{
"error": {
"code": "validation_error",
"internal_code": 113,
"message": "The request is invalid.",
"request_id": "req_01JC8Z…",
"details": [
{ "field": "exp_date", "issue": "Invalid ISO date", "code": "invalid_format" }
]
}
}
| Campo | Descrição |
|---|---|
code | código estável do erro. Use este campo no seu código. |
internal_code | número do erro, útil ao falar com o suporte |
message | descrição em inglês, para pessoas. Pode mudar: não use para decisões no código |
request_id | identificador da requisição. Também vem no cabeçalho X-Request-Id de todas as respostas |
details | quando existe: lista de problemas por campo, ou um objeto com informações extras |
Falando com o suporte
Informe sempre o request_id. Com ele encontramos a requisição exata nos registros.
Códigos
| HTTP | code | Interno | Quando acontece | O que fazer |
|---|---|---|---|---|
| 400 | invalid_json | 117 | o corpo não é um JSON válido | corrija o JSON |
| 401 | invalid_api_key | 101 | chave ausente, inválida, revogada, expirada ou enviada na URL | confira a chave e o cabeçalho |
| 402 | subscription_inactive | 105 | a organização está sem assinatura ativa | regularize a assinatura |
| 403 | api_access_not_enabled | 102 | a API não está liberada para a organização | peça acesso no painel |
| 403 | api_access_suspended | 103 | o acesso foi suspenso | fale com o suporte |
| 403 | workspace_not_eligible | 104 | a chave é de um espaço pessoal | use uma organização |
| 403 | insufficient_scope | 108 | a chave não tem o escopo necessário (details.required_scope) | use uma chave com o escopo certo |
| 403 | terms_not_accepted | 130 | o prazo para aceitar a nova versão dos termos terminou | o dono ou um administrador aceita os termos no painel |
| 404 | not_found | 110 | rota, item ou id inexistente, ou item de outra organização | confira o id |
| 406 | not_acceptable | 115 | o Accept pede um formato que não é JSON nem XML | use JSON ou XML |
| 409 | conflict | 128 | o id enviado em um POST já existe | use outro id ou consulte o item |
| 409 | store_has_products | 111 | excluir loja com produtos sem cascade=true (details traz as contagens) | veja Lojas |
| 409 | idempotency_in_progress | 129 | a mesma Idempotency-Key ainda está em processamento | espere o Retry-After e repita |
| 412 | precondition_failed | 112 | o If-Match não confere com a versão atual (o ETag atual vem na resposta) | leia o item de novo e decida |
| 413 | payload_too_large | 118 | corpo maior que 256 KB | divida em requisições menores |
| 415 | unsupported_media_type | 116 | corpo que não é application/json | envie JSON |
| 422 | validation_error | 113 | parâmetro ou campo inválido, campo desconhecido ou referência inválida | veja details |
| 422 | idempotency_key_reused | 114 | mesma Idempotency-Key com outro corpo ou outra rota | use uma chave nova para cada operação |
| 429 | rate_limited | 106 | limite por minuto | espere o Retry-After |
| 429 | quota_exceeded | 107 | cota mensal esgotada | espere a renovação ou peça mais cota |
| 500 | internal_error | — | erro inesperado do Validades | tente de novo depois; se continuar, fale com o suporte |
O código store_restricted (109) está reservado para chaves restritas a uma loja, que ainda não existem.
Erros de validação
Em validation_error, details lista cada problema:
| Campo do detalhe | Descrição |
|---|---|
field | o campo ou parâmetro com problema (por exemplo exp_date, limit) |
issue | o problema, em inglês |
code | tipo do problema (por exemplo invalid_format, too_big, unrecognized_keys, not_found, inactive) |
Exemplos comuns:
- campo que não existe no recurso →
unrecognized_keys; brand_id,category_id,store_idouproduct_idde outra organização ou inexistente →issue: not_foundno campo;- loja desativada em
store_id→issue: inactive.
Tentando de novo
| Situação | Repetir? |
|---|---|
429, 409 idempotency_in_progress | sim, depois do Retry-After |
500, falha de rede, tempo esgotado | sim, com intervalos crescentes. Em POST, use Idempotency-Key para não criar duplicados |
4xx (exceto os acima) | não: corrija a requisição antes |