15. Manejo Centralizado de Errores, Códigos HTTP Adecuados y Middlewares de Captura
Crea middlewares de cuatro argumentos (err, req, res, next) para capturar excepciones sincrónicas y asíncronas, devolviendo respuestas JSON estandarizadas.
La Regla de los 4 Argumentos en Express
Muchos desarrolladores cometen el error de colocar bloques try/catch repetitivos en cada ruta, devolviendo respuestas de error con formatos inconsistentes.
Express.js cuenta con un mecanismo integrado para centralizar todos los fallos: el middleware de manejo de errores. Express lo identifica mediante una firma estricta de exactamente cuatro argumentos:
// ¡Express detecta que es un capturador de errores por tener 4 parámetros!
app.use((err, req, res, next) => {
console.error('[Error no controlado]:', err.stack);
res.status(err.statusCode || 500).json({
error: true,
mensaje: err.message || 'Error interno del servidor'
});
});
Ubicación crítica: Este middleware debe definirse después de todas las demás rutas al final del archivo principal.
Captura de Errores en Funciones Asíncronas (async/await)
En Express 4, si una función async lanza un error y no está envuelta en un try/catch, la promesa quedará rechazada (Unhandled Promise Rejection) y Express no la enviará automáticamente al middleware de error, dejando la petición colgada.
Para solucionar esto de forma limpia, se utiliza la función auxiliar catchAsync:
// Función de orden superior que atrapa cualquier excepción asíncrona
export const catchAsync = (fn) => (req, res, next) => {
fn(req, res, next).catch(next); // Delega el fallo en el middleware de error
};
Seguridad en Producción: Ocultar el Stack Trace
err.stack a los clientes en producción. La traza de pila expone nombres de tablas, variables de entorno, rutas absolutas del disco del servidor y versiones de dependencias que facilitan ataques. Condiciona siempre el stack a process.env.NODE_ENV !== 'production'.
⚡ Arquitectura Completa de Manejo de Errores con Clases Personalizadas
Patrón profesional de captura centralizada con AppError, catchAsync y sanitización de salida:
// error-handling.js - Sistema Centralizado de Errores en Express
import express from 'express';
const app = express();
app.use(express.json());
// 1. Clase de Error Personalizada para Errores Operacionales Conocidos
class AppError extends Error {
constructor(message, statusCode) {
super(message);
this.statusCode = statusCode;
this.isOperational = true; // Error controlado (ej. 404, 400, 401)
Error.captureStackTrace(this, this.constructor);
}
}
// 2. Wrapper para envolver controladores asíncronos y evitar try/catch repetitivo
const catchAsync = (fn) => (req, res, next) => {
fn(req, res, next).catch(next);
};
// 3. Ruta de ejemplo que dispara un error operacional 400
app.get('/api/usuarios/:id', catchAsync(async (req, res, next) => {
const { id } = req.params;
if (id === 'invalido') {
throw new AppError('El ID proporcionado no es compatible con el formato UUID', 400);
}
// Simulación de búsqueda exitosa
res.json({ id, nombre: 'Nicolás Gómez', rol: 'Estudiante Kilopolis' });
}));
// 4. Capturador de Rutas No Encontradas (404)
app.all('*', (req, res, next) => {
next(new AppError(`No se puede encontrar la ruta ${req.originalUrl} en este servidor`, 404));
});
// 5. Middleware Global de Error (Exactamente 4 argumentos)
app.use((err, req, res, next) => {
const statusCode = err.statusCode || 500;
const isProd = process.env.NODE_ENV === 'production';
res.status(statusCode).json({
ok: false,
status: statusCode,
mensaje: err.message || 'Error interno del servidor',
// Solo enviamos el stack de depuración si estamos en desarrollo
...(isProd ? {} : { stack: err.stack })
});
});
app.listen(3000, () => console.log('Servidor con manejo de errores activo en :3000'));
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Cómo distingue Express.js un middleware estándar de un middleware especial de manejo de errores?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar Node.js & npm Profesional y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.