メインコンテンツまでスキップ

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" }
]
}
}
CampoDescrição
codecódigo estável do erro. Use este campo no seu código.
internal_codenúmero do erro, útil ao falar com o suporte
messagedescrição em inglês, para pessoas. Pode mudar: não use para decisões no código
request_ididentificador da requisição. Também vem no cabeçalho X-Request-Id de todas as respostas
detailsquando 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​

HTTPcodeInternoQuando aconteceO que fazer
400invalid_json117o corpo não é um JSON válidocorrija o JSON
401invalid_api_key101chave ausente, inválida, revogada, expirada ou enviada na URLconfira a chave e o cabeçalho
402subscription_inactive105a organização está sem assinatura ativaregularize a assinatura
403api_access_not_enabled102a API não está liberada para a organizaçãopeça acesso no painel
403api_access_suspended103o acesso foi suspensofale com o suporte
403workspace_not_eligible104a chave é de um espaço pessoaluse uma organização
403insufficient_scope108a chave não tem o escopo necessário (details.required_scope)use uma chave com o escopo certo
403terms_not_accepted130o prazo para aceitar a nova versão dos termos terminouo dono ou um administrador aceita os termos no painel
404not_found110rota, item ou id inexistente, ou item de outra organizaçãoconfira o id
406not_acceptable115o Accept pede um formato que não é JSON nem XMLuse JSON ou XML
409conflict128o id enviado em um POST já existeuse outro id ou consulte o item
409store_has_products111excluir loja com produtos sem cascade=true (details traz as contagens)veja Lojas
409idempotency_in_progress129a mesma Idempotency-Key ainda está em processamentoespere o Retry-After e repita
412precondition_failed112o If-Match não confere com a versão atual (o ETag atual vem na resposta)leia o item de novo e decida
413payload_too_large118corpo maior que 256 KBdivida em requisições menores
415unsupported_media_type116corpo que não é application/jsonenvie JSON
422validation_error113parâmetro ou campo inválido, campo desconhecido ou referência inválidaveja details
422idempotency_key_reused114mesma Idempotency-Key com outro corpo ou outra rotause uma chave nova para cada operação
429rate_limited106limite por minutoespere o Retry-After
429quota_exceeded107cota mensal esgotadaespere a renovação ou peça mais cota
500internal_error—erro inesperado do Validadestente 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 detalheDescrição
fieldo campo ou parâmetro com problema (por exemplo exp_date, limit)
issueo problema, em inglês
codetipo 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_id ou product_id de outra organização ou inexistente → issue: not_found no campo;
  • loja desativada em store_id → issue: inactive.

Tentando de novo​

SituaçãoRepetir?
429, 409 idempotency_in_progresssim, depois do Retry-After
500, falha de rede, tempo esgotadosim, com intervalos crescentes. Em POST, use Idempotency-Key para não criar duplicados
4xx (exceto os acima)não: corrija a requisição antes