Toda API vai falhar. O banco de dados vai dar timeout. O servico de terceiros vai retornar lixo. O usuario vai enviar um request que sua validacao nao antecipou. A questao nao e se sua API vai ter erros, e se seu tratamento de erros vai tornar essas falhas debugaveis, recuperaveis e invisiveis para o usuario quando possivel.
Codigos de status HTTP
Use os codigos corretamente: 400 para requests malformados, 401 para nao autenticado, 403 para nao autorizado, 404 para recurso inexistente, 422 para validacao falha, 429 para rate limit. Nunca retorne 200 com um erro no body.
Formato de resposta de erro
Um formato consistente baseado no RFC 7807: status code, codigo legivel por maquina (como "VALIDATION_ERROR"), mensagem legivel por humanos, array de detalhes para erros de campo, e um requestId para debugging.
Logica de retentativas com backoff exponencial
Para chamadas a servicos externos, implemente retentativas com backoff exponencial: comece com um delay curto, dobre apos cada falha, adicione jitter aleatorio. So retente erros transitorios (5xx, timeouts, 429). Nunca retente erros 4xx.
Padrao Circuit Breaker
Se um servico esta fora do ar, retentar cada request 3 vezes so triplica a carga. O circuit breaker monitora a taxa de falhas e quando ultrapassa um limite, para de fazer chamadas por um periodo de cooldown.
O que o tratamento de erros nao cobre
Tratamento de erros lida com erros individuais. Monitoramento observa o agregado e alerta quando padroes emergem. Para cobrir esse gap, combine o tratamento de erros com um error tracker ou uma ferramenta de monitoramento que registre taxa de erros e tempos de resposta por rota e avise quando eles disparam. No Next.js, o instrumentation.ts é o hook oficial para conectar isso.
Tratamento de erros também é superfície de ataque: handlers que vazam stack traces ou pulam a validação de inputs passam fácil num code review. O pentester com IA da Nurbak escaneia seu repositório em busca de endpoints sem verificação de auth e outros bugs exploráveis, e pode abrir um PR com a correção. Seu primeiro scan é grátis.