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.
