Manejo de Errores en Express

Centraliza las respuestas de error con middleware de errores de cuatro argumentos y deja que Express 5 maneje las promesas rechazadas automáticamente.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

import express, { type Request, type Response, type NextFunction } from "express";
 
class AppError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public code?: string
  ) {
    super(message);
  }
}
 
const app = express();
 
app.get("/users/:id", async (req, res) => {
  const user = await findUser(req.params.id);
  if (!user) throw new AppError(404, "User not found", "USER_NOT_FOUND");
  res.json(user);
});
 
app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
  const status = err instanceof AppError ? err.statusCode : 500;
  const code = err instanceof AppError ? err.code : "INTERNAL_ERROR";
  res.status(status).json({ error: err.message, code });
});

Cuándo usarlo: Cualquier API que devuelva formas de error consistentes en lugar de rastreos de pila HTML o solicitudes colgadas.

Ejemplo Funcional

import express, { type Request, type Response, type NextFunction } from "express";
import { z } from "zod";
 
class AppError extends Error {
  constructor(public statusCode: number, message: string) {
    super(message);
  }
}
 
const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});
 
const app = express();
app.use(express.json());
 
function validateBody<T>(schema: z.ZodSchema<T>) {
  return (req: Request, _res: Response, next: NextFunction) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      next(new AppError(422, result.error.message));
      return;
    }
    req.body = result.data;
    next();
  };
}
 
app.post("/users", validateBody(createUserSchema), async (req, res) => {
  const user = await createUser(req.body);
  res.status(201).json(user);
});
 
app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
  console.error(err);
  const status = err instanceof AppError ? err.statusCode : 500;
  res.status(status).json({
    error: status === 500 ? "Internal server error" : err.message,
  });
});
 
async function createUser(data: z.infer<typeof createUserSchema>) {
  return { id: 1, ...data };
}

Lo que esto demuestra:

• AppError personalizado con códigos de estado
• Middleware de validación que llama a next(err) en lugar de manejar en línea
• El manejador asíncrono de Express 5 lanza errores reenviados al middleware de errores
• Mensajes 500 seguros para producción (sin fuga de pila)

Análisis Profundo

Cómo Funciona

• Los errores síncronos en los manejadores de rutas son capturados por Express
• Express 5 captura automáticamente las promesas rechazadas de los manejadores async
• next(err) salta el middleware restante y va al primer manejador de 4 argumentos
• El middleware de errores debe registrarse después de todas las rutas

Estándares de Respuesta de Error

Notas de TypeScript

// Manejador de errores tipado
const errorHandler: express.ErrorRequestHandler = (err, _req, res, _next) => {
  res.status(500).json({ error: "Internal server error" });
};
app.use(errorHandler);

Errores comunes

• Olvidaste registrar el middleware de errores - Express por defecto envía páginas de error HTML. Solución: añade un manejador de 4 argumentos al final.
• Llamar a res.json() y luego a next(err) - choque por doble respuesta. Solución: retorna después de enviar, nunca llames a next después de responder.
• next(err) en el middleware de errores - pasa al siguiente manejador de errores; llamar a next() sin err salta al middleware regular. Solución: finaliza la respuesta en el manejador de errores final.
• Exponer err.stack en producción - fuga de información. Solución: registra la pila en el servidor, envía un mensaje genérico al cliente.
• No manejar 404 por separado - las rutas desconocidas pasan sin respuesta. Solución: añade un 404 general antes del manejador de errores.
• Express 4 asíncrono sin envoltorio - las promesas rechazadas no manejadas bloquean el proceso. Solución: actualiza a Express 5 o usa try/catch.

Alternativas

Preguntas Frecuentes

Relacionado

• Orden de Middleware - ubicación del manejador de errores
• Migración a Express 5 - cambios en errores asíncronos
• Middleware de Seguridad - no filtres errores
• Estándares de Respuesta de Errores - formas de error de API
• Mejores Prácticas de Express - lista de verificación de la sección

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.