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. Nurbak Watch preenche esse gap para apps Next.js — roda dentro do servidor via instrumentation.ts, 5 linhas de codigo, alertas via Slack, email ou WhatsApp em menos de 10 segundos. $29/mes (gratis no beta).