Separar estado, tipo e ocorrência
RFC 9457 define application/problem+json. Use um tipo estável e detalhe compreensível; o cliente não deve interpretar prosa traduzida para decidir. Se existir status, mantenha-o coerente com o estado HTTP transmitido.
| Estado | Significado HTTP | Tratamento a considerar |
|---|---|---|
| 400 | Pedido incorreto | Corrigir antes de repetir. |
| 401 | Faltam credenciais válidas | Verificar credenciais e mecanismo previsto. |
| 403 | Pedido compreendido mas recusado | Rever direitos; repetir não os concede. |
| 503 | Serviço temporariamente indisponível | Esperar e repetir com limites se permitido. |
Prever caminhos de falha
- Documente códigos, formatos e tratamento esperado. Teste respostas vazias, conteúdo não JSON de gateways, ligações interrompidas e timeouts.
- Valide entradas e permissões no servidor. Trate falhas esperadas sem ocultar anomalias desconhecidas; não apresente uma falha funcional como sucesso.
- Devolva um identificador de correlação útil para suporte. Exclua stack traces, consultas internas, palavras-passe e tokens das respostas públicas.
Repetir apenas quando adequado
5xx não autoriza ciclos ilimitados. Combine contrato, estado, idempotência e prazo global. Comunique um defeito com reprodução mínima expurgada; após correção, teste o caso original e recusas de acesso próximas.
Fontes primárias
Os erros da API devem orientar a ação sem vazamento de informações.
O status HTTP fornece uma categoria inicial, mas um cliente pode precisar de um tipo estável e detalhes úteis. A RFC 9457 descreve uma estrutura de problema comum; ela não justifica a exposição de rastreamentos internos ou dados sensíveis.
- Separe recusa permanente, entrada corrigível e falha temporária.
- Documente o tipo, o status e a possível ação do cliente para cada erro importante.
- Teste se as respostas não contêm segredos ou payloads completos desnecessários.
Fonte primária: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar o guia prático.
Tentativas API: contar o orçamento completo de tempo
Defina limite de chamadas e prazo global.
Caso pedagógico fictício: os números não representam a CIE nem clientes.
Modelo fictício: quatro chamadas até 250 ms e esperas de 100, 200 e 400 ms. Exclui jitter, ligação, filas e validação local.
- Tentativas totais
- 41 + 3
- Esperas acumuladas (ms)
- 700100 + 200 + 400
- Orçamento modelado (ms)
- 17004 × 250 + 700
| Passo | Chamada máxima (ms) | Espera seguinte (ms) |
|---|---|---|
| Tentativa 1 | 250 | 100 |
| Tentativa 2 | 250 | 200 |
| Tentativa 3 | 250 | 400 |
| Tentativa 4 | 250 | 0 |
| Total | 1000 | 700 |
- Tempo das chamadas1.000
- Esperas acumuladas700
- Prazo global (ms)1.500
Verificações antes de concluir
- 1.000 + 700 = 1.700 ms excede o prazo de 1.500 ms.
- Propague o prazo global e evite efeitos duplicados; timeout não prova cancelamento remoto.
Experimentar um orçamento de tentativas
n × T + W × (2^(n−1) − 1)
Método relacionado: consultar o guia prático.
Erros API: tipos, estados e provas
As notas detalhadas desta edição estão disponíveis em inglês.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5