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:
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¿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.