Pular para o conteúdo principal
Quando algo dá errado, a API retorna um status HTTP de erro (4xx/5xx) e um corpo JSON no formato padrão abaixo.

​
Formato do erro

{
  "error": {
    "code": "CONFLICT",
    "message": "E-mail já cadastrado",
    "key": "errors.conflict.duplicate_email",
    "params": { "email": "joao@example.com" },
    "details": { }
  }
}
CampoSempre presenteDescrição
codeSimCódigo estável e legível por máquina (ex.: NOT_FOUND, VALIDATION_ERROR).
messageSimMensagem legível (fallback em pt-BR).
keyNãoChave de i18n, quando a mensagem é traduzível.
paramsNãoParâmetros de interpolação da mensagem (ex.: { "email": "..." }).
detailsNãoDetalhes adicionais (ex.: erros por campo na validação).
Programe sua lógica em cima do code (e do status HTTP), nunca do texto de message — o texto pode mudar ou vir traduzido.

​
Códigos HTTP

StatusCódigo típicoSignificadoO que fazer
400VALIDATION_ERRORCorpo/parâmetros inválidos.Corrigir o payload. Ver details.
401UNAUTHORIZEDAPI key ausente ou inválida.Verificar o header x-api-key.
403FORBIDDENSem permissão para a operação.Verificar o tipo/escopo da chave.
404NOT_FOUNDRecurso não existe (ou é de outra conta).Conferir o ID.
409CONFLICTConflito de estado (duplicado, transição inválida).Tratar o caso específico.
422UNPROCESSABLE_ENTITYRequisição entendida, mas não processável.Revisar a regra de negócio.
429RATE_LIMIT_EXCEEDEDLimite de requisições excedido.Aguardar e repetir com backoff.
500 / 502 / 503INTERNAL_ERRORErro no servidor.Repetir com backoff; se persistir, contatar o suporte.

​
Erros de validação (400)

Quando um ou mais campos são inválidos, details traz a mensagem por campo: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validação",
    "details": {
      "items": "É necessário pelo menos 1 item",
      "payments": "Soma dos payments (5000) deve ser igual ao total dos items (4990)"
    }
  }
}

​
Tratamento recomendado

Retry com backoff

Em 429 e 5xx, repita com backoff exponencial. Combine com Idempotency-Key para não duplicar a operação.

Não faça retry em 4xx

400/409/422 não se resolvem repetindo — corrija a requisição.

Logue o code e o request id

Guarde code, status e o corpo para diagnóstico. Não logue a API key.

Idempotência sempre

Em escrita, use Idempotency-Key para que retries sejam seguros. Ver Convenções.