A lo largo del módulo han ido quedando cabos sueltos, todos del mismo tipo. cargarEvento propaga EVENTO_NO_ENCONTRADO con siguiente(error). El dominio lanza AFORO_INSUFICIENTE cuando la Sala Bóveda ya no tiene entradas. express.json() rechaza un cuerpo malformado. El middleware validar de 06-06 llama a siguiente(new ErrorDeValidacion(...)), una clase que todavía no existe. Y el middleware 404 de 06-03 propaga RUTA_NO_ENCONTRADA. Nadie recoge nada de eso. En esta lección construimos el destino común: un manejador central que convierte cualquier fallo en una respuesta coherente, y una política clara sobre qué se puede convertir en una respuesta amable y qué no. Es la última pieza del módulo, y la que le da sentido a la tabla ESTADO_POR_CODIGO del módulo 4.

1. El middleware de error y su firma de cuatro argumentos
2. El manejador por defecto de Express
3. Errores síncronos, asíncronos y la gran mejora de Express 5
4. Una jerarquía de errores propia
5. ESTADO_POR_CODIGO encuentra su sitio
6. Errores operativos frente a errores de programación
7. El manejador central completo
8. El middleware 404
9. Errores fuera de Express
10. Lista de comprobación del módulo

Un middleware de error es idéntico a los demás salvo por una cosa: tiene cuatro parámetros.

Express distingue los dos tipos inspeccionando fn.length, la aridad de la función: si vale 4, es manejador de errores; si no, es middleware normal. Los síntomas de la versión mala son desconcertantes: los errores siguen mostrándose con el formato por defecto de Express, y en las peticiones correctas aparece un 500 inexplicable, porque tu función recibe (req, res, next) y trata req como si fuera un error. Si no usas siguiente, decláralo igualmente: configura ESLint para permitir argumentos no usados al final, o llámalo _siguiente, pero no lo quites.

Un manejador de errores solo captura lo propagado desde middleware y rutas registrados por encima de él. Registrarlo en medio significa que todo lo declarado después escapa a su control: si escribes aplicacion.use(manejadorDeErrores) y solo después aplicacion.use('/api', crearRutasApi()), los errores de la API no llegan a él. Es el mismo principio del orden de 06-04, aplicado al final de la cadena.

Un manejador de errores puede llamar a siguiente(error) para pasarlo al siguiente, igual que en la cadena normal, lo que sirve para separar responsabilidades: aplicacion.use(registrarError) registra y propaga, aplicacion.use(errorDeValidacion) trata solo un tipo o propaga, y aplicacion.use(manejadorFinal) responde siempre. Lo que no debe ocurrir nunca es que el último no responda.

Si no registras ninguno, Express tiene el suyo, y hace tres cosas sensatas: usa error.status o error.statusCode si existen (si no, responde 500); fija las cabeceras que traiga error.headers; y envía el cuerpo del error, con una diferencia crítica según el entorno:

Ese comportamiento es correcto y merece la pena entender por qué. Una traza de pila revela rutas absolutas del servidor (/home/despliegue/escena-viva/src/...), nombres de módulos internos, versiones de bibliotecas y a veces fragmentos de datos: un mapa gratis para quien esté buscando por dónde entrar. En desarrollo la quieres ver entera; en producción no debe salir del servidor jamás. Nuestro manejador propio mantiene exactamente esa política, pero con nuestro formato JSON en lugar de HTML. Un detalle a menudo ignorado: Express asume NODE_ENV=production para esto, y en Escena Viva usamos produccion en español, así que hay que ser explícitos y no depender de la comparación interna del framework —por eso nuestro manejador consulta configuracion.esProduccion.

Los errores síncronos Express siempre los ha capturado: un throw dentro de un manejador síncrono va al manejador de errores, sin más.

En Express 4, el framework llamaba al manejador, este devolvía una promesa que nadie observaba, y el rechazo se convertía en un unhandledRejection sin respuesta al cliente: ni error visible, ni 500, ni nada, solo el cliente esperando. Si te encuentras asyncHandler, express-async-handler, catchAsync o wrapAsync en un proyecto, ya sabes qué son: restos de Express 4. En Express 5 sobran, y quitarlos elimina una capa de ruido de cada ruta.

Esa última fila es la excepción que no desaparece. Express solo puede observar la promesa que le devuelves:

La regla: si un error puede ocurrir dentro de una devolución de llamada, promisifica esa operación. Es una razón más para preferir fs.promises y las utilidades de los módulos 2 y 3.

Hasta ahora creabas errores con Object.assign(new Error(...), { codigo }). Funciona, pero no permite distinguir tipos con instanceof, no obliga a nada y se escribe distinto en cada sitio. Vamos a formalizarlo.

Decisiones que merecen explicación:

• this.name = new.target.name: cada subclase se identifica con su propio nombre en los registros, sin repetirlo a mano; y { cause } preserva el error original al envolverlo, con la cadena completa para el registro y sin filtrarla al cliente.
• this.estado opcional deja que el dominio lance errores con solo un código, sin saber nada de HTTP; Error.captureStackTrace elimina el constructor de la traza, que empieza donde de verdad ocurrió el fallo; y esOperativo = true es la marca central del apartado 6.

Uso en el dominio, que sigue sin conocer HTTP:

En el módulo 4 escribiste src/servidor/errores-http.js con estadoParaError, cuerpoParaError y la tabla ESTADO_POR_CODIGO, que vivía repartida por los manejadores de respuestas.js. Ahora tiene un único cliente: el manejador central.

La cascada de cuatro pasos hace que todo encaje en el mismo sitio: nuestra jerarquía, los códigos que el dominio lanza sin saber de HTTP y los errores de terceros. Para estos últimos conviene además normalizar el código, para que el cliente vea siempre el vocabulario de Escena Viva:

Esta distinción es la que decide qué se cuenta al cliente y qué no:

Cómo se distinguen en el código:

Por qué el bug devuelve un 500 mudo. Si un TypeError se filtra al cliente con su mensaje, publicas el nombre de tus variables internas, la línea del fichero y, con la traza, medio árbol de directorios. Además, ese mensaje no le sirve de nada a quien llama: no puede corregir su petición porque el problema no está en ella. Un 500 con el identificador de la petición es más útil para todos: el cliente sabe que el fallo es tuyo y tiene una referencia con la que reclamar, y tú tienes la traza completa en tus registros.

Dos respuestas reales, una operativa y otra de bug:

La segunda no dice absolutamente nada del fallo, pero en los registros del servidor está la traza completa asociada a ese mismo idPeticion que el cliente tiene delante. Esa correlación —el identificador de 06-04 apareciendo en la respuesta y en el registro— es lo que convierte un informe de incidencia inútil ("me dio error") en uno accionable ("me dio error, referencia 3b71e0a2").

Por qué va antes del manejador de errores y después de las rutas: es un middleware normal, no de error, y Express lo alcanza cuando ninguna ruta anterior ha respondido. Si lo pusieras antes de las rutas, respondería 404 a todo; si lo pusieras después del manejador de errores, nunca se ejecutaría. Y propaga en lugar de responder para que el 404 pase por el mismo punto que los demás errores y salga con codigo, estado, idPeticion y el mismo formato: curl -s localhost:3000/api/no-existe devuelve {"error":{"codigo":"RUTA_NO_ENCONTRADA","mensaje":"No se ha encontrado ruta GET /api/no-existe",...}}. Un cliente que sabe interpretar tus errores no debería necesitar un caso especial para el 404.

Express solo ve lo que ocurre dentro de una petición; hay dos sucesos del proceso que se le escapan:

La tentación es evidente: capturar el error, registrarlo y dejar el servidor en pie para no perder el servicio. Es un error grave, y estas son las razones:

1. El estado del proceso es desconocido. La excepción se propagó por una pila que no la esperaba: hay funciones a medias, con variables actualizadas parcialmente. En Escena Viva, una excepción en mitad de GestorDeVentas.registrar puede dejar las entradas descontadas del aforo pero el pedido sin crear.
2. Se pierden recursos. Cada excepción no capturada puede dejar sin cerrar un descriptor de fichero, un socket o un temporizador: el proceso "sobrevive" degradándose hasta agotar la memoria.
3. Oculta el bug. Un servidor que sigue funcionando mal no genera urgencia, y el fallo se acumula durante semanas. Además, el comportamiento por defecto de uncaughtException sin manejador es terminar, y así debe ser.

La política correcta, y la que aplicamos, es: registrar el error entero → dejar de aceptar peticiones nuevas → dar unos segundos a las peticiones en curso → terminar el proceso → que el supervisor lo reinicie. Quién reinicia es asunto del entorno, y en el módulo 11 lo veremos con nombres propios: PM2 en modo cluster, restart: always en Docker o el reinicio automático de un contenedor gestionado. La aplicación no se reinicia a sí misma: se muere con dignidad y deja que el supervisor haga su trabajo.

Antes de dar Escena Viva por terminada, repasa punto por punto:

• [ ] crearAplicacion() en src/app.js no llama a listen y devuelve la aplicación; src/servidor.js crea el servidor http, arranca y registra el apagado ordenado.
• [ ] src/config/index.js es el único sitio que lee process.env, y valida al arrancar; x-powered-by desactivado y trust proxy acorde al despliegue real.
• [ ] Routers en src/rutas/ y controladores en src/controladores/, ambos sin lógica de negocio; rutas ordenadas de específica a genérica, con el comodín el último.
• [ ] Todos los caminos de cada middleware responden o llaman a siguiente, y el orden es el canónico de 06-05: id, seguridad, CORS, registro, compresión, límites, cuerpo, estáticos, rutas, 404, errores.
• [ ] express.json() con limit; express.static con dotfiles: 'ignore'; helmet activo con la CSP ajustada al front-end en lugar de desactivada.
• [ ] CORS con lista blanca desde configuración, nunca '*' con credentials; límite de peticiones en POST /api/pedidos.
• [ ] Toda entrada validada con esquema en el borde (y en req.datosValidados, no reasignando req.query); el dominio conserva sus invariantes.
• [ ] Jerarquía de errores en src/errores.js y manejador central el último; traza en la respuesta solo fuera de producción, e idPeticion en las respuestas de error y en los registros.
• [ ] unhandledRejection y uncaughtException registran y terminan ordenadamente; npm audit limpio y dependencias revisadas con el criterio del módulo 5.

• Olvidar el cuarto parámetro. Sin siguiente, Express trata tu manejador como middleware normal: nunca recibe errores y rompe las peticiones sanas.
• Registrarlo antes que las rutas. Solo captura lo declarado por encima.
• Filtrar la traza en producción o tratar los bugs como errores operativos. Publicas rutas del sistema y versiones, y un TypeError detallado no ayuda al cliente pero a ti te delata; compruébalo con NODE_ENV=produccion antes de desplegar. Y no sigas tras un uncaughtException: el proceso queda en estado desconocido, así que registra y termina.
• Responder cuando res.headersSent ya es true. Provoca Cannot set headers after they are sent; comprueba la bandera y delega en Express.
• Perder la causa al envolver errores. Usa new Error(mensaje, { cause: original }); sin ella la traza empieza donde envolviste, no donde falló. Y mantén trivial el propio manejador: si hace JSON.stringify de algo con referencias circulares, fallará en el peor sitio posible.
• Consejo: prueba tus errores. En el módulo 9, con supertest, verifica que un aforo insuficiente devuelve 409 con AFORO_INSUFICIENTE, que un :id inválido devuelve 400 y que un bug forzado devuelve un 500 sin traza en producción.

Implementa src/errores.js completo y haz que el dominio lo use. Comprueba con curl cuatro casos, todos con idPeticion: GET /api/eventos/evt-999 → 404 EVENTO_NO_ENCONTRADO; POST /api/pedidos con cantidad: 99 → 400 DATOS_INVALIDOS con detalles; POST /api/pedidos pidiendo más entradas de las libres → 409 AFORO_INSUFICIENTE; y GET /api/no-existe → 404 RUTA_NO_ENCONTRADA.

Añade una ruta /api/depuracion/fallo que provoque un TypeError real (leer una propiedad de undefined). Comprueba que con NODE_ENV=desarrollo la respuesta incluye traza, que con NODE_ENV=produccion devuelve el 500 mudo, y que en ambos casos stderr muestra la traza completa con el prefijo [BUG] y el idPeticion.

Crea dos rutas async que rechacen, una envuelta en asyncHandler y otra sin envolver, y comprueba en Express 5 que se comportan igual. Después escribe un manejador que lance dentro de un setTimeout y explica por qué ese sí tumba el proceso, y cómo lo arreglarías.

Solución 1

Fíjate en la diferencia entre los dos últimos: cantidad: 99 es un problema de forma (400, lo detecta el esquema sin mirar el estado del sistema); pedir 6 entradas cuando quedan 3 es un problema de estado (409, solo lo puede detectar el dominio en ese instante). Son los dos niveles de 06-06 funcionando.

Solución 2

En ambos casos, stderr muestra la misma traza completa precedida de [BUG] 3b71e0a2-... GET /api/depuracion/fallo 500 TypeError.

Solución 3

Con curl, /a, /b y /d devuelven un 500 con su mensaje —las dos primeras, idénticas—, mientras que /c mata el proceso con un uncaughtException, porque su throw ocurre en un tic posterior del bucle de eventos (módulo 2), en una pila donde ya no hay nada de Express, y la promesa que el manejador devolvió —ninguna, en este caso— no puede observar ese fallo. El arreglo es /d: promisificar la espera para que el throw ocurra dentro de la cadena async que Express sí observa. Conclusión práctica: asyncHandler es innecesario en Express 5, pero promisificar sigue siendo obligatorio.

Con esta lección se cierra el módulo 6, y Escena Viva es ya una API Express completa. Los errores tienen por fin un destino único. Sabes que el manejador de error se identifica por sus cuatro parámetros y que olvidar el último lo convierte en un middleware normal con síntomas desconcertantes; que va registrado el último porque solo ve lo declarado por encima; y que el manejador por defecto de Express filtra la traza en producción y la muestra en desarrollo, política que tu manejador propio reproduce con tu formato JSON. Has visto la gran mejora de Express 5 —un manejador async que rechaza llega solo al manejador de errores, y asyncHandler pasa a ser una reliquia de Express 4— con su única excepción viva: lo que ocurre dentro de una devolución de llamada sigue siendo cosa tuya, y por eso se promisifica.

Has construido una jerarquía propia en src/errores.js con ErrorDeAplicacion y sus subclases ErrorDeValidacion, RecursoNoEncontrado y ConflictoDeEstado, y la tabla ESTADO_POR_CODIGO que escribiste en el módulo 4 ha encontrado por fin su sitio definitivo: un único punto donde los códigos del dominio, los de tu jerarquía y los de los paquetes de terceros se traducen a estados HTTP. Distingues los errores operativos —esperables, explicados al cliente con detalle— de los errores de programación —registrados enteros, devueltos como un 500 mudo con solo el identificador de petición como referencia—. Y fuera de Express, unhandledRejection y uncaughtException registran y terminan el proceso ordenadamente, sin fingir que no ha pasado nada, dejando el reinicio a un supervisor que llegará en el módulo 11.

Mira ahora el proyecto entero. crearAplicacion() se prueba sin arrancar nada. La configuración se lee y se valida en un solo sitio. Los routers de /api/eventos, /api/sesiones y /api/pedidos viven en ficheros de treinta líneas con sus controladores al lado. Tus middleware propios miden, identifican y controlan la caché; los de terceros añaden cabeceras de seguridad, CORS, registro, compresión y límites de uso. Los esquemas de zod describen exactamente qué acepta cada endpoint. Y cualquier fallo, venga de donde venga, sale con la misma forma y con un identificador que lo enlaza con los registros del servidor. Eso es una API de producción. Pero hay algo que no ha cambiado desde el módulo 3, y ya empieza a incomodar: los datos siguen viviendo en datos/eventos.json. Cada venta reescribe un fichero entero. Dos compradores que pulsan "comprar" a la vez para las últimas entradas de la Sala Bóveda leen ambos el mismo aforo, ambos ven que hay sitio y ambos escriben. El fichero acaba con las ventas del segundo y las del primero desaparecen, o peor: se venden más entradas de las que caben en la sala. Ninguna validación de esquema evita eso, ningún middleware lo detecta y ningún manejador de errores lo puede arreglar, porque no es un error: es una carrera entre dos escrituras.

En el módulo 7 los datos dejan de vivir en un JSON. Empezaremos por entender qué es una base de datos y qué aporta frente a un fichero, modelaremos Escena Viva con MongoDB y Mongoose, escribiremos el CRUD completo, exploraremos relaciones y consultas avanzadas, veremos el mundo SQL con Sequelize y terminaremos con migraciones, semillas y —lo que estabas esperando— transacciones, que son exactamente la respuesta al problema del aforo y la sobreventa que acabamos de describir. El JSON nos ha servido durante siete módulos; ha llegado el momento de jubilarlo.