Manejo de status codes HTTP en NestJS

Contenido del curso

Fundamentos y Primer CRUD

Base de Datos y Persistencia con TypeORM

Autenticación y Autorización

Tu API Completa

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0016:07

Manejo de status codes HTTP en NestJS

Curso de Backend con NestJS

Clase 6 de 35

Clase 6 / 35

Recursos

El manejo de errores en una API define qué tan profesional y útil resulta para quienes la consumen. Aprender a devolver el status code correcto en NestJS te permite comunicar con precisión qué pasó con cada request, ya sea desde una app móvil, una web o un servicio externo que se conecta a tu backend.

¿Qué son los status codes y por qué importan en una API?

Los códigos de estado HTTP son la forma estándar en que un servidor le dice al cliente cómo terminó su petición. No son opcionales: librerías y frameworks los leen automáticamente para decidir qué mostrar.

Los rangos principales que vas a usar son:

1xx: el request fue recibido y sigue en proceso, útil para colas de tareas.
2xx: todo salió bien. El 200 indica éxito y el 201 que un recurso fue creado.
3xx: redirección o recurso que cambió de lugar.
4xx: error del cliente. Aquí entran el 400 Bad Request, el 401 Unauthorized, el 403 Forbidden, el 404 Not Found y el 422 Unprocessable Entity.
5xx: el servidor falló, por ejemplo cuando se rompe la conexión a la base de datos.

¿Qué diferencia hay entre 401 y 403? El 401 indica que no estás autenticado, mientras que el 403 significa que sí estás autenticado pero no tienes permiso para ese recurso específico.

¿Cómo validar datos antes de lanzar una excepción?

Antes de devolver errores, conviene validar la entrada. En el reto de la clase, la idea era validar si un email es realmente un email. Como el update es dinámico, primero guardas changes.email y luego compruebas si existe.

Una validación mínima usa includes para buscar la arroba:

js const email = changes.email; if (email) { if (!email.includes('@')) { throw new UnprocessableEntityException('email is not valid'); } }

Esto cumple el requerimiento básico, aunque lo ideal es una expresión regular mucho más completa. Más adelante se inyecta una capa de validación profesional a Node.js, pero el principio se mantiene: si el dato no cumple, no sigas con la operación.

¿Cómo lanzar excepciones HTTP en NestJS?

NestJS expone excepciones desde @nestjs/common que se traducen automáticamente al status code correcto. En vez de hacer return con un mensaje, usas throw y el framework arma la respuesta con el formato adecuado.

El patrón más común aparece en el método findOne. Si el ID no existe en el array de usuarios, el status correcto es 404:

js throw new NotFoundException(User #${id} not found);

Al probar en Postman, la respuesta deja de ser un 200 con texto plano y pasa a tener message, error: "Not Found" y statusCode: 404. Eso es lo que las apps cliente esperan leer.

¿Qué es NotFoundException en NestJS? Es una excepción de @nestjs/common que devuelve automáticamente un status 404 con un JSON estructurado que incluye message, error y statusCode.

¿Cuándo usar UnprocessableEntityException?

Cuando los datos llegan bien formados pero no pasan una validación de negocio, como un email sin arroba, el status apropiado es 422. En NestJS lo lanzas con UnprocessableEntityException. También existe BadRequestException, que devuelve 400 y funciona para entradas mal formadas en general, pero para validaciones específicas el 422 comunica mejor la intención.

¿Cómo bloquear acceso con ForbiddenException?

Si una regla de negocio impide devolver cierto recurso, lanzas ForbiddenException, que retorna un 403. Por ejemplo, bloquear el acceso al usuario con ID 1:

js if (id === 1) { throw new ForbiddenException('not allowed'); }

En Postman, pedir el usuario 2 devuelve 200 con su información, pedir uno inexistente devuelve 404, y pedir el 1 devuelve 403 con el mensaje de no autorizado. Cada caso queda claro para quien consume la API.

¿Cómo elegir la excepción correcta para cada caso?

NestJS mantiene una correspondencia uno a uno entre sus excepciones built-in y los status codes HTTP. La regla práctica es pensar primero en qué le quieres comunicar al cliente y después buscar la excepción que lo representa.

Una guía rápida con las más usadas:

NotFoundException: 404, recurso inexistente.
BadRequestException: 400, request mal formado.
UnauthorizedException: 401, falta autenticación.
ForbiddenException: 403, autenticado pero sin permiso.
UnprocessableEntityException: 422, validación de negocio fallida.
InternalServerErrorException: 500, falla del servidor.

Cuando la misma validación se repite en varios métodos, como el chequeo de existencia del usuario, conviene extraerla a un método privado sin decoradores y reutilizarla. Mantienes el controlador limpio y la lógica de errores centralizada.

El reto: revisa la documentación de NestJS, recorre todas las excepciones disponibles y empareja cada una con su status code. ¿Cuál te parece más útil para tu proyecto actual? Cuéntalo en los comentarios.

Juan Diego Mejia Maestre

Hace 6 meses•editado

🚀 Manejo de Status Codes en NestJS

El uso de códigos de estado HTTP correctos transforma una API funcional en una API profesional. En NestJS, esto se logra mediante el manejo estratégico de excepciones.

Todos los HttpCode explicado por

Perro:

Gatos:

🎨 Alternativas Visuales (HTTP Codes)

Además de http.dog y http.cat, existen estas opciones para consultar códigos de forma divertida:

🦆 HTTP Garden (Patos):
🍕 HTTP Pizza (Pizzas):
🐟 HTTP Fish: — Si prefieres la vida marina para tus errores.
🐐 HTTP Goats (Cabras):

🛠️ Recursos Técnicos (No solo memes)

Si estás programando en NestJS y necesitas precisión quirúrgica, estos sitios son mejores que los de animales:

HTTP Statuses:
- Es una referencia limpia, rápida y sin distracciones. Te da la definición exacta de la RFC (el estándar oficial).
HTTP.dev:
- Explicaciones detalladas sobre cuándo usar un código sobre otro (ej. la diferencia real entre un 401 y un 403).

📌 ¿Por qué son vitales?

Los códigos de estado actúan como el lenguaje universal entre el servidor y el cliente (Web/Móvil). Sin ellos, el frontend no sabría si mostrar un mensaje de error, redirigir al login o limpiar un formulario.

🔢 Códigos Imprescindibles

✅ 200 OK: Petición exitosa.
✨ 201 Created: Recurso (usuario, post) creado con éxito.
🚫 400 Bad Request: Error del cliente (falta un dato).
🔐 401 Unauthorized: Falta autenticación.
🕵️ 404 Not Found: El recurso no existe.
❌ 422 Unprocessable Entity: Error de validación (ej. email mal escrito).
🔥 500 Internal Server Error: Algo explotó en nuestro código.

🛠️ Ejemplos de Excepciones en NestJS

En NestJS, no usas return para los errores, usas throw new. Aquí tienes cómo se ve cada uno en el código:

1. 🟢 Success (200/201)

200 OK: Para búsquedas exitosas.
201 Created: Al guardar un nuevo registro. > return { id: 1, name: 'Juan Diego' }; // NestJS asume 200 o 201 automáticamente.

2. 🟠 Client Errors (4xx)

400 - BadRequestException: Cuando el cliente olvida un campo.
- throw new BadRequestException('Falta el nombre de usuario');
401 - UnauthorizedException: Si el token no existe.
- throw new UnauthorizedException('Debes iniciar sesión');
403 - ForbiddenException: Tiene token, pero no es admin.
- throw new ForbiddenException('No tienes permisos de administrador');
404 - NotFoundException: No existe el ID en la DB.
- throw new NotFoundException('El usuario con ID 5 no existe');
422 - UnprocessableEntityException: Error de formato (ej. email inválido).
- throw new UnprocessableEntityException('El formato del email es incorrecto');

3. 🔴 Server Errors (5xx)

500 - InternalServerErrorException: Fallo inesperado (ej. la DB se cayó).
- throw new InternalServerErrorException('Error crítico en el servidor');
503 - ServiceUnavailableException: El servidor está en mantenimiento.
- throw new ServiceUnavailableException('Servidor en mantenimiento');

🔥 Pro-Tip para Obsidian

Para tu proyecto Quantico, puedes personalizar el mensaje y el cuerpo del error así:

throw new BadRequestException({
  status: HttpStatus.BAD_REQUEST,
  error: 'Datos incompletos',
  project: 'Quantico'
});

Fundamentos y Primer CRUD

Crea una API RESTful con NestJS

Instalación del CLI de NestJS y primer proyecto con API

Creación de endpoints dinámicos para consultar usuarios en NestJS

Operaciones CRUD en APIs REST con Postman

Método PUT para actualizar usuarios con ID automático

Manejo de status codes HTTP en NestJS

DTOs y validación automática de datos en APIs con NestJS

Servicios y lógica de negocio en NestJS

Variables de entorno seguras en NestJS

Programación modular en NestJS con UserModule

Base de Datos y Persistencia con TypeORM

Configuración de PostgreSQL con Docker y Docker Compose

Configuración de PostgreSQL con TypeORM en aplicaciones NestJS

Creación de entidades ORM con decoradores en TypeScript

Repository Pattern con TypeORM en NestJS

Relaciones uno a uno entre usuarios y perfiles en PostgreSQL

Actualización de DTOs con mapped types en NestJS para perfil y usuario

Generación automática de módulos CRUD con NestJS y AI

Relación uno a muchos con TypeORM

CRUD de categorías con IA en NestJS

Relaciones many-to-many con TypeORM y validación de arrays

Reutilización de servicios entre módulos en NestJS

Migraciones en TypeORM sin perder datos

Cómo evitar perder datos al migrar columnas

Autenticación y Autorización

Hashing de contraseñas con Bcrypt en NestJS

Excluir campos sensibles con ClassTransformer

Autenticación local con Passport en NestJS

Endpoint de login con Passport en NestJS

Implementación de JSON Web Token para autenticación en NestJS

Rutas protegidas con JWT en NestJS

User ID automático desde JWT en NestJS

Tu API Completa

Autogenera resúmenes e imágenes con OpenAI en NestJS

Documentación automática de APIs con Swagger en NestJS

Preparar tu API NestJS para producción

Desplegar aplicación Node.js a producción con Railway y PostgreSQL

Desarrollo de API REST escalable con NestJS en producción

Manejo de status codes HTTP en NestJS