O tratamento de erros no Next.js e dividido em dois mundos. No lado do cliente, voce tem error boundaries com error.tsx. No lado do servidor, tem try/catch em API routes e server components. Em producao, existem erros que nao aparecem em nenhum dos dois — so se manifestam com trafego real, dados reais e condicoes que seu desenvolvimento local nunca simula.
Cliente: error.tsx
O App Router usa um arquivo chamado error.tsx para criar error boundaries. Coloque-o em qualquer segmento de rota e ele captura erros de runtime do seu page.tsx irmao e todas as rotas filhas. Deve ser um client component ('use client'). Recebe o erro e uma funcao reset() para retentar.
Error boundary global: global-error.tsx
global-error.tsx envolve toda a aplicacao incluindo o root layout. E o error boundary de ultimo recurso. Deve incluir suas proprias tags <html> e <body> porque substitui o root layout quando acionado.
Servidor: tratamento de erros em API Routes
Crie um wrapper withErrorHandling que envolve seus handlers em try/catch. Erros conhecidos sao lancados como AppError com status codes apropriados. Erros desconhecidos sao capturados, logados e retornados como 500 generico. Nunca exponha stack traces ao cliente.
Erros que so aparecem em producao
Dados reais sujos, concorrencia, falhas de servicos de terceiros, cold starts e diferencas de ambiente causam erros que o testing local nao antecipa. Seu error handling os captura mas ninguem esta olhando.
Nurbak Watch usa instrumentation.ts para monitorar cada API route de dentro do servidor. 5 linhas de codigo, alertas via Slack, email ou WhatsApp em menos de 10 segundos quando as taxas de erro sobem. $29/mes (gratis durante o beta).