Tema 6 · Exception Filters

6. Manejo de Errores con HttpException y Filtros de Excepción Personalizados (@Catch)

Lanza excepciones semánticas nativas (NotFoundException, BadRequestException) y construye filtros globales para estandarizar respuestas de error JSON.

La Capa Global de Excepciones en NestJS

NestJS incluye una capa de manejo de excepciones integrada que procesa automáticamente todos los errores no capturados en tu aplicación. Cuando un servicio lanza una excepción derivada de HttpException, Nest la convierte en una respuesta JSON limpia con el código de estado HTTP correspondiente.

Excepción Nativa (@nestjs/common) Código HTTP Cuándo lanzarla en un Servicio
BadRequestException 400 Reglas de negocio inválidas (ej. cupo del curso agotado o fecha vencida).
UnauthorizedException 401 Token JWT ausente, inválido o credenciales de inicio de sesión incorrectas.
ForbiddenException 403 El usuario está autenticado pero su rol no tiene permiso para ejecutar la acción.
NotFoundException 404 El recurso solicitado por ID o slug no existe en la base de datos.
ConflictException 409 Intento de registrar un correo electrónico o código de curso que ya existe.

Filtros de Excepción Personalizados (@Catch)

Si necesitas que todas las respuestas de error de tu API incluyan campos adicionales (como timestamp, path o un código de rastreo para auditoría), puedes implementar la interfaz ExceptionFilter y decorarla con @Catch(HttpException).

⚡ Filtro Global de Excepciones HTTP Estandarizado

Implementación de HttpExceptionFilter para estructurar errores con marca de tiempo, ruta y estado:

src/common/filters/http-exception.filter.ts
Solo lectura
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus
      ? exception.getStatus()
      : HttpStatus.INTERNAL_SERVER_ERROR;

    const exceptionResponse = exception.getResponse();
    const mensaje =
      typeof exceptionResponse === 'object' && exceptionResponse !== null && 'message' in exceptionResponse
        ? (exceptionResponse as Record<string, unknown>).message
        : exception.message;

    response.status(status).json({
      exito: false,
      codigoEstado: status,
      mensaje,
      ruta: request.url,
      fecha: new Date().toISOString(),
    });
  }
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué excepción nativa de @nestjs/common debes lanzar en un servicio cuando un estudiante intenta registrarse con un correo electrónico que ya existe en la base de datos?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar NestJS Framework 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.