Toda API va a fallar. La base de datos va a hacer timeout. El servicio de terceros va a devolver basura. El usuario va a mandar un request que tu validacion no anticipo. La pregunta no es si tu API va a tener errores — es si tu manejo de errores va a hacer que esas fallas sean debuggeables, recuperables e invisibles para el usuario cuando sea posible.
Codigos de estado HTTP
Usa los codigos correctamente: 400 para requests malformados, 401 para no autenticado, 403 para no autorizado, 404 para recurso inexistente, 422 para validacion fallida, 429 para rate limit. Nunca devuelvas 200 con un error en el body.
Formato de respuesta de error
Un formato consistente basado en RFC 7807: status code, codigo legible por maquina (como "VALIDATION_ERROR"), mensaje legible por humanos, array de detalles para errores de campo, y un requestId para debugging.
Logica de reintentos con backoff exponencial
Para llamadas a servicios externos, implementa reintentos con backoff exponencial: empieza con un delay corto, duplicalo tras cada fallo, agrega jitter aleatorio. Solo reintenta errores transitorios (5xx, timeouts, 429). Nunca reintenties errores 4xx.
Patron Circuit Breaker
Si un servicio esta caido, reintentar cada request 3 veces solo triplica la carga. El circuit breaker monitorea la tasa de fallos y cuando supera un umbral, deja de hacer llamadas por un periodo de cooldown.
Lo que el manejo de errores no cubre
Error handling maneja errores individuales. Monitoreo observa el agregado y te alerta cuando emergen patrones. Nurbak Watch llena este gap para apps Next.js — corre dentro del servidor via instrumentation.ts, 5 lineas de codigo, alertas via Slack, email o WhatsApp en menos de 10 segundos. $29/mes (gratis en beta).