Cómo gestionar errores HTTP en NestJS sin complicaciones

Cuando desarrollamos aplicaciones, los errores en la API pueden ocurrir en cualquier momento: solicitamos datos que no existen, la base de datos no responde o un servicio externo falla. ¿Cómo podemos capturar y manejar estos errores en la API?

Por ejemplo, en la Jumbo API, tenemos los métodos de búsqueda y actualización en cards.service. ¿Qué ocurre si el ID no existe o si la actualización de la tarjeta no se completa con éxito?

No te preocupes, NestJS ofrece una forma sencilla de manejar errores y responder con mensajes claros para el cliente. ¡Vamos a resolverlo!

Este artículo es parte de mi serie sobre NestJS.

Manejar excepciones con HttpException

Inicia la API con el comando npm run start:dev. Luego, abre el navegador y consulta un ID de tarjeta que no exista en el endpoint:

http://localhost:3000/cards/list/1698691077473

La API responde vacía y no sabemos con certeza qué está pasando. La mejor alternativa es notificar al cliente que la tarjeta solicitada no existe.

La forma más directa de solucionarlo es usando HttpException, que nos permite enviar un mensaje de error acompañado del código de estado HTTP correspondiente.

Vamos a implementarlo: primero verificamos si la tarjeta es null antes de retornar el valor. Si no existe, usamos la clase HttpException para lanzar el error. HttpException espera un mensaje y un código de estado.

El código final queda así:

getById(id: string): Card {
    const card = this.cards.find((card) => card.id === +id);
    if (!card) {
      throw new HttpException(
        `Sorry, card ${id} was not found`,
        HttpStatus.NOT_FOUND,
      );
    }
    return card;
  }

Guarda los cambios y vuelve a consultar el mismo ID en el navegador:

¡Listo! Ahora recibimos una respuesta clara indicando que la tarjeta no existe.

Aunque HttpException resuelve el problema, NestJS cuenta con opciones todavía más limpias para los casos de error más frecuentes.

Uso de excepciones HTTP integradas

NestJS ofrece un conjunto de las excepciones HTTP más comunes listas para usar, lo que facilita el manejo de escenarios como BadRequestException, UnauthorizedException, NotFoundException, ForbiddenException, entre otras.

Consulta la lista completa de excepciones HTTP integradas en la documentación de NestJS.

Vamos a simplificar nuestro código usando estas excepciones integradas. Reemplazamos HttpException por NotFoundException. Solo requiere el mensaje descriptivo y NestJS se encarga de asignar el código de estado automáticamente.

  getById(id: string): Card {
    const card = this.cards.find((card) => card.id === +id);
    if (!card) {
      throw new NotFoundException(`Sorry, card ${id} was not found`);
    }
    return card;
  }

Guarda los cambios y realiza la prueba nuevamente:

¡Mantenemos el mismo control de errores escribiendo menos código!

Ahora bien, ¿qué pasa si olvidamos capturar algún error que rompa la aplicación, como una librería externa que arroja una excepción no controlada?

NestJS intercepta el error mediante su capa de excepciones y envía una respuesta adecuada al cliente por nosotros. Vamos a forzar un error para comprobar cómo responde el framework:

  getById(id: string): Card {
    const card = this.cards.find((card) => card.id === +id);
    throw Error('Ups something fail');
  }

Guarda los cambios otra vez y haz la prueba:

Como puedes ver, recibimos un mensaje estructurado con un código 500, evitando que el servidor se detenga ante fallos imprevistos.

Resumen

En este artículo aprendimos a gestionar errores en una API con NestJS. Vimos cómo usar la clase HttpException para emitir mensajes comprensibles y cómo apoyarnos en las excepciones integradas (built-in) para los errores más habituales. También revisamos cómo la capa de excepciones de NestJS captura fallos inesperados de forma automática, garantizando respuestas claras para los consumidores de la API.

Si quieres revisar más a fondo este tema, te recomiendo consultar la documentación oficial de NestJS.