Erros e códigos HTTP
Como tratar validação, ausência de dados, autenticação, limites e dependências indisponíveis.
Erros usam JSON com o campo detail. Os endpoints gerados na referência descrevem os códigos aplicáveis.
| Código | Significado | Ação recomendada |
|---|---|---|
200 | consulta concluída | valide também fonte.status nas listas |
304 | conteúdo não mudou | reutilize a resposta associada ao ETag |
401 | chave ausente, inválida, expirada ou revogada | verifique header, ambiente e rotação |
404 | registro válido não encontrado | não repita sem mudança de entrada/dados |
422 | parâmetro inválido | corrija formato, faixa ou enumeração |
429 | limite por minuto excedido | aguarde Retry-After e aplique jitter |
503 | fonte ou dependência indisponível | tente depois com backoff e monitore status |
Exemplo:
{ "detail": "CNPJ inválido" }Lista vazia não é sempre “nenhum resultado”
Listagens relacionadas retornam 200 e itens: [] quando a fonte não possui snapshot, acompanhados de:
{
"itens": [],
"paginacao": { "limite": 20, "offset": 0, "total": 0 },
"fonte": { "status": "indisponivel", "versao": null }
}Interprete fonte.status: "indisponivel" como ausência do dataset publicado, não como confirmação de que não existem ocorrências.
Retentativas
Retente somente falhas transitórias: 429, 503, timeout e falha de rede. Use backoff exponencial, jitter, timeout explícito e um limite de tentativas. Não retente 401, 404 ou 422 sem alterar a causa.