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.
Desde o Next.js 15 você pode exportar onRequestError em instrumentation.ts para capturar todos os erros do servidor em um só lugar e enviá-los para o seu error tracker ou plataforma de logs. Depois, acompanhe tempos de resposta e taxas de erro por endpoint e configure alertas quando uma rota passar da linha de base.
O tratamento de erros também é superfície de ataque: um stack trace vazado ou uma rota sem checagem de auth é exatamente o que um atacante procura. O pentester com IA da Nurbak escaneia seu repositório em busca de checagens de auth faltando e outros bugs exploráveis, e pode abrir um PR com a correção. Seu primeiro scan é grátis.