Erros

Formato

Respostas de erro usam JSON. Em muitos casos o corpo inclui error (mensagem) e, em validação, detalhes por campo.

Exemplo típico:

{ "error": "Credencial inválida ou ausente" }

Quando a loja não é informada:

{
  "error": "Informe o CPF/CNPJ da loja ou a chave de acesso (?loja=...) para continuar.",
  "code": "STORE_NOT_SPECIFIED"
}

Em 422, o corpo pode trazer a lista de problemas de validação (campos e mensagens).

Códigos HTTP

Código	Significado	O que fazer
400	Loja não informada (STORE_NOT_SPECIFIED)	Envie X-Store-Slug ou ?loja=
401	Credencial ausente, inválida ou revogada	Verifique Authorization / X-API-Key
403	Sem permissão ou plano sem acesso à API	Ajuste perfil/plano; confira entitlements
404	Recurso não encontrado (ou loja inválida)	Confira IDs, slug e path
409	Conflito (ex.: GTIN duplicado)	Ajuste o payload ou trate o conflito
422	Validação do corpo/query	Leia os detalhes e corrija os campos
429	Rate limit	Aguarde e retente com backoff
5xx	Erro interno	Retente; se persistir, contate o suporte

Boas práticas

• Trate 401/403 como falha de configuração, não como “tente de novo” em loop
• Em 429, respeite o intervalo (backoff exponencial)
• Logue o corpo da resposta em 422 para depurar integrações
• Não exponha a chave de API em mensagens de erro ao usuário final