Tema 15 · Manejo de Errores

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

⚠️ Riesgo de Información Sensible: Nunca envíes 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
Solo lectura
// 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
1 Pregunta
Pregunta 1
¿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.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.