API códigos de erro e best pratices
1) Por que normalizar erros
Previsibilidade para os clientes: formato único e comportamento de retrações.
Acelera o debag: 'trace _ id '/' request _ id', 'erro _ código' estável.
Segurança: o SQL/stack traces/configs não será arrastado.
Observabilidade: relatórios por taxonomia de erro (validação, quotas, temporizações etc.).
2) Princípios básicos
1. Um único formato de resposta para todos os 4xx/5xx (e para os 2xx com erros parciais - um padrão separado).
2. Semântica HTTP clara: O status correto é mais importante.
3. Dois níveis de código: transporte ('status') e domínio estável 'error _ código'.
4. Retriable vs Não-retriable: Especifique claramente e dê uma dica sobre o back-off.
5. Segurança padrão: detalhes - somente ao cliente com permissões; sem pistas internas.
6. Localização: o código de máquina permanece estável, o texto é traduzido.
3) Formato de erro unificado (baseado em RFC 7807)
Recomendado pelo JSON («Aplicação/protem + json» avançada):json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}Obrigatório: 'tipo', 'title', 'status', 'erro _ código', 'trace _ id'.
Opcional: 'errors []', 'retriable', 'hint', 'meta'.
- `Content-Type: application/problem+json`
- `X-Request-ID`/`Traceparent` (W3C)
- (para 429/503) 'Retry-After' (segundos ou data)
4) Semântica HTTP estates (fusão entre «clássicos» e práticas)
2xx (sucesso com nuances)
200 OK é um sucesso normal.
201 Created - o recurso foi criado.
202 Accepted - Asincrona na fila (dê 'status _ url').
207 Multi-Status - Sucesso parcial (evite se possível).
4xx (erro do cliente)
400 Bad Request - sintaxe/formato, mas não validação de campos (melhor que 422).
401 Unauthorized - Não/não é o token correto. Vamos 'WWW-Autenticate'.
403 Forbidden - O token é validado, mas faltam direitos (RBAC/ABAC/limites).
404 Not Found - recurso/endpoint ausente.
409 Conflict - conflito de versões/estados (optimistic locking, idempotency).
410 Gone - endpoint removido para sempre.
412 Precisition Failed - ETag/If-Match falhou.
415 Unsupported Media Tipo - Errado 'Content-Estando'.
422 Unprocessable Entity - validação de regras de negócios.
429 Too Many Requests - Quotas/velocidade excedidas (Consulte no ° 7).
5xx (erro no servidor)
500 Internal Server Erro - Erro súbito; Não divulgar detalhes.
502 Bad Gateway - Erro de upstream.
503 Service Unavailable - degradação/superaquecimento, dê «Retry-After».
504 Gateway Timeout - Tempo de Backend.
5) Taxonomia de domínios 'erro _ código'
Recomendamos as faixas:- 'AUTH _' - autenticação/autorização.
- 'VAL _' - Validação de entrada.
- 'RATELIMIT _' - quotas e velocidade.
- 'IDEMP _' - Idempotidade/Duplicação.
- 'CONFLICT _' - versões/status.
- 'DEP _' é um vício (PSP/DNS/SMTP).
- 'PAY _' é um erro de negócio do domínio de pagamento.
- 'SEC _' - Segurança (assinaturas, HMAC, mTLS).
- 'INT _' é interior súbito.
- Estabilidade no tempo (back-compat).
- Descrições e exemplos no catálogo de erros (docs + machine-readable JSON).
6) Retriable vs Non-retriable
Campos:- `retriable: true|false`
- Se 'true' é obrigatório 'Retry-After' (em segundos) ou contrato 'back-off exponencial (a partir de 1-2 c, max 30-60 s)'.
Retriable normalmente «502/503/504», alguns «500», «429» (após a janela).
Non-retriable: `400/401/403/404/409/410/415/422`.
7) Rate limit & cota erros (429)
Corpo:json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}- `Retry-After: 12`
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- Для квот: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`
8) Idempotidade e conflitos
Os pedidos de gravação são 'Idempotency-Key' (exclusivo entre 24 e 72 h).
Conflito de reativação → 409 Confidt com 'erro _ código:' IDEMP _ REPLAY '.
Conflito de versões do recurso por ETag → 412 Precisition Failed.
Na resposta, anexe 'resource _ id '/' status _ url' para uma nova consulta segura.
9) Validação e 422
Devolva a lista de erros de campo:json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}- Não duplique o mesmo entre 400 e 422 preferidos para validação de negócios.
- As mensagens são humanas; «código» é de máquina.
10) Segurança de erros
Nunca: stack traces, SQL, caminhos de arquivos, nomes privados de hosts.
Edite o PII; acompanhe o GDPR/DSAR.
Para assinar/NMAS: Distingue 'SEC _ SCORE _ MISMATCH' (403) e 'SEC _ TIMESTAMP _ SKEW' (401/403) com a dica «verifique o tempo de £5 min».
11) Correlação e observação
Adicione sempre 'trace _ id '/' X-Request-ID' e coloque no logs/pistas.
Os erros são agregados por 'error _ código' e 'status', como 'top erros', 'new vs known'.
Alerts: flutuação 5xx/422/429, latência p95, share of errors.
12) gRPC/GraphQL/Webhooks - mappings
gRPC ↔ HTTP
GraphQL
Transporte 200, mas 'errors []' dentro - adicione 'extensões. code` и `trace_id`.
Para «fatal» (autenticação/quotas), melhor HTTP real 401/403/429.
Webhooks
Leia apenas 2xx do destinatário como um sucesso.
Retrai com back-off exponencial, 'X-Webhook-ID', 'X-Sinais'.
410 do destinatário - parar o retrai (endpoint removido).
13) Versionização de erros
'tipo '/' erro _ código' - estáveis; novos - apenas adicionar.
Se você alterar o padrão corporal, aumente a versão menor da API ou 'problem + json; v=2`.
Documentação: tabela de códigos + exemplos; changelog erros.
14) Documentação (OpenAPI fatias)
Respostas globais
yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }Exemplo de endpoint
yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }15) Testes e qualidade
Contrato-teste: conformidade 'aplicação/projem + json', campos obrigatórios.
Testes negativos: todos os ramos 401/403/404/ 409/422/429/500.
Chaos/latency: verificação de retratos em 5xx/ 503/504/429 ('Retry-After').
Seguro testes: falta de mensagens internas, máscara PII correta.
Backward-compat: clientes antigos compreendem novos campos (adicione, não rompa).
16) Folha de cheque de implementação
- Unificado 'problem + json' + estáveis 'error _ código'.
- Semântica correta HTTP/gRPC/GraphQL.
- Retriable/não-retriable + 'Retry-After '/recomendações de back-off.
- Títulos rate-limit e 429 comportamentos.
- Idempotidade ('Idempotency-Key', 409/412).
- Segurança: sem stack traces/segredos, edição PII.
- 'trace _ id '/' X-Request-ID' em todos os erros.
- Documentação do catálogo de erros e exemplos.
- Monitoramento por taxonomia de erro.
- Auto-eixos de cenários negativos.
17) Mini-FAQ
O que é que 400 é diferente de 422?
400 - pedido quebrado (sintaxe/tipo de conteúdo). 422 é uma prova de sintaxe, mas as regras de negócios não passaram.
Quando é 401 e quando é que é 403?
401 - não/não está certo; 403 - O token está a comer, não tem razão.
É sempre necessário 'Retry-After'?
Para 429/503, sim; para os outros retriable - é recomendável fazer uma recomendação explícita.
Resultado
Erros bem projetados são um contrato: status HTTP correto, um único 'protem + json', 'erro _ código' estável, dicas claras sobre retais e segurança rigorosa. Normalize o formato, documente a taxonomia, adicione telemetria e testes - e sua API se tornará previsível, segura e amigável aos integradores.