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. Para cubrir ese gap, combiná tu manejo de errores con un error tracker o una herramienta de monitoreo que registre tasa de errores y tiempos de respuesta por ruta y te avise cuando se disparan. En Next.js, instrumentation.ts es el hook oficial para conectarlo.
El manejo de errores también es superficie de ataque: handlers que filtran stack traces o se saltean la validación de inputs se escapan fácil en un code review. El pentester con IA de Nurbak escanea tu repo buscando endpoints sin chequeo de auth y otros bugs explotables, y puede abrir un PR con el fix. Tu primer escaneo es gratis.