Erros

A API devolve o mesmo envelope em toda falha:

{
  "status": "error",
  "message": "Pedido não encontrado"
}

O corpo de sucesso não carrega o campo status. Ele traz o dado direto.

Falha de validação

O código é 422 e o corpo ganha um campo a mais, com um array de mensagens por campo:

{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "cnpj": ["CNPJ inválido"],
    "valor": ["Expected number, received string"]
  }
}

Trate errors como mapa de campo para lista. Um campo pode acumular mais de uma mensagem.

Códigos que você precisa tratar

Código	Quando acontece	O que fazer
`400`	A requisição está malformada.	Corrija a chamada. Não repita igual.
`401`	O token está ausente, expirado ou inválido.	Peça um token novo e repita uma vez.
`403`	O token é válido, mas o recurso não é seu.	Não repita. Confira o identificador.
`404`	O recurso não existe ou não pertence a você.	Não repita. Veja a nota abaixo.
`409`	Conflito de estado. O corpo traz `"Conflict."`.	Leia o recurso antes de repetir.
`422`	A validação recusou o corpo.	Corrija os campos listados em `errors`.
`429`	Você passou do limite de chamadas.	Espere e repita com recuo exponencial.
`500`	Falha interna. O corpo traz `"Did something wrong happen"`.	Repita com recuo. Abra chamado se persistir.
`503`	Um serviço de apoio está fora.	Repita com recuo.

A nota importante sobre 404

A API responde 404, e não 403, quando o recurso existe mas pertence a outro grupo.
Esse comportamento é deliberado: um 403 revelaria que o identificador existe.

Logo, 404 significa "não existe para você". Não conclua que o recurso foi apagado.

Rota inexistente

Uma URL desconhecida devolve 404 com a mensagem no formato do método e do caminho:

{
  "status": "error",
  "message": "Route GET /api/v1/naoexiste not found"
}

Cuidado com o host de sandbox de hoje

Enquanto mock.apidog.com não for provisionado, ele devolve 200 para toda
requisição, inclusive POST, porque um CloudFront de catch-all mapeia erro do bucket para a
página inicial com status 200.

Consequência prática: naquele host o seu tratamento de erro nunca dispara. Um teste que só
verifica status < 400 passa sem a API existir.

Como saber que você está falando com a API de verdade, e não com o catch-all:

O corpo de uma resposta da API é JSON. O do catch-all é HTML, e começa com <!DOCTYPE html>.

A API devolve 404 com {"status":"error"} para rota inexistente. O catch-all devolve 200.

Cheque o Content-Type antes de confiar no status.

Como repetir a chamada

Repita apenas 429, 500, 502, 503 e 504. Use recuo exponencial com jitter:
1 s, 2 s, 4 s, 8 s, com teto de cinco tentativas.

Nunca repita 400, 401 sem token novo, 403, 404, 409 ou 422. A resposta não muda.

Falha de validação#

Códigos que você precisa tratar#

A nota importante sobre 404#

Rota inexistente#