El manejo de errores en Next.js esta dividido en dos mundos. Del lado del cliente, tenes error boundaries con error.tsx. Del lado del servidor, tenes try/catch en API routes y server components. En produccion, existen errores que no aparecen en ninguno de los dos — solo se manifiestan con trafico real, datos reales y condiciones que tu desarrollo local nunca simula.
Cliente: error.tsx
El App Router usa un archivo llamado error.tsx para crear error boundaries. Colocalo en cualquier segmento de ruta y captura errores de runtime de su page.tsx hermano y todas las rutas hijas. Debe ser un client component ('use client'). Recibe el error y una funcion reset() para reintentar.
Error boundary global: global-error.tsx
global-error.tsx envuelve toda la aplicacion incluyendo el root layout. Es el error boundary de ultimo recurso. Debe incluir sus propias tags <html> y <body> porque reemplaza el root layout cuando se activa.
Servidor: manejo de errores en API Routes
Crea un wrapper withErrorHandling que envuelve tus handlers en try/catch. Errores conocidos se lanzan como AppError con status codes apropiados. Errores desconocidos se capturan, loguean y retornan como 500 generico. Nunca expongas stack traces al cliente.
Errores que solo aparecen en produccion
Datos reales sucios, concurrencia, fallos de servicios de terceros, cold starts y diferencias de entorno causan errores que el testing local no anticipa. Tu error handling los captura pero nadie esta mirando.
Nurbak Watch usa instrumentation.ts para monitorear cada API route desde dentro del servidor. 5 lineas de codigo, alertas via Slack, email o WhatsApp en menos de 10 segundos cuando las tasas de error suben. $29/mes (gratis durante la beta).