Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

La gestion des exceptions (HttpException, NotFoundException…)

Cette leçon explique comment NestJS transforme les exceptions en réponses HTTP. Dix routes exécutées montrent le corps exact produit par NotFoundException sans message, avec message, avec description,...

0 chapitres 0 QCM Accès gratuit
La gestion des exceptions (HttpException, NotFoundException…)

À propos de ce cours

Cette leçon explique comment NestJS transforme les exceptions en réponses HTTP. Dix routes exécutées montrent le corps exact produit par NotFoundException sans message, avec message, avec description, avec une liste ou un objet, par HttpException générique, par une exception métier personnalisée, et par des erreurs non HTTP (TypeError, Error) qui deviennent des 500 au détail masqué. La leçon présente la liste des exceptions intégrées, le choix du bon statut, l'option cause et les bonnes pratiques pour les services. Activités corrigées.

Objectifs de la leçon

  • Comprendre comment NestJS transforme une exception en réponse HTTP.
  • Utiliser les exceptions intégrées et leurs différentes formes.
  • Choisir le bon code de statut.
  • Créer une exception métier réutilisable.
  • Savoir ce que devient une erreur qui n'est pas une HttpException.
Le filtre d'exception par défaut

Vous lancez des exceptions depuis le chapitre 06 (throw new NotFoundException()). Elles sont attrapées par un filtre d'exception global intégré à NestJS, qui fabrique la réponse. Sa règle :

  • si l'exception est une HttpException (ou une classe dérivée), son statut et son contenu sont utilisés ;
  • sinon, la réponse est 500 avec le message générique « Internal server error ».

Exceptions HTTP intégrées de NestJS

Toutes dérivent de HttpException.

Les différentes formes, exécutées

📄 src/common/exceptions/stagiaire-introuvable.exception.ts

import { HttpException, HttpStatus } from '@nestjs/common';

// Exception métier réutilisable
export class StagiaireIntrouvableException extends HttpException {
  constructor(id: number) {
    super({ statusCode: HttpStatus.NOT_FOUND, code: 'STAGIAIRE_INTROUVABLE', message: `Stagiaire ${id} introuvable` },
          HttpStatus.NOT_FOUND);
  }
}

📄 src/exceptions.controller.ts

import {
  BadRequestException, ConflictException, Controller, ForbiddenException, Get, HttpException, HttpStatus,
  NotFoundException, Param, ParseIntPipe, UnprocessableEntityException,
} from '@nestjs/common';
import { StagiaireIntrouvableException } from './stagiaire-introuvable.exception';

@Controller('exceptions')
export class ExceptionsController {
  @Get('simple')
  simple() {
    throw new NotFoundException();                                   // message par défaut
  }

  @Get('message')
  message() {
    throw new NotFoundException('Groupe DEV999 introuvable');          // message personnalisé
  }

  @Get('description')
  description() {
    throw new ConflictException("L'e-mail est déjà utilisé", { description: 'Doublon' });
  }

  @Get('liste')
  liste() {
    throw new BadRequestException(['nom trop court', 'e-mail invalide']);
  }

  @Get('objet')
  objet() {
    throw new UnprocessableEntityException({ code: 'GROUPE_COMPLET', message: 'Le groupe DEV101 est complet', places: 0 });
  }

  @Get('generique')
  generique() {
    throw new HttpException('Trop de requêtes, patientez', HttpStatus.TOO_MANY_REQUESTS);
  }

  @Get('interdit')
  interdit() {
    throw new ForbiddenException();
  }

  @Get('metier/:id')
  metier(@Param('id', ParseIntPipe) id: number) {
    throw new StagiaireIntrouvableException(id);
  }

  @Get('bug')
  bug() {
    const stagiaire: any = undefined;
    return stagiaire.nom;                                            // TypeError, pas une HttpException
  }

  @Get('erreur')
  erreur() {
    throw new Error('Connexion à la base perdue (mot de passe : secret123)');
  }
}

Résultat réellement obtenu :

GET /api/exceptions/simple → 404 {"message":"Not Found","statusCode":404}
GET /api/exceptions/message → 404 {"message":"Groupe DEV999 introuvable","error":"Not Found","statusCode":404}
GET /api/exceptions/description → 409 {"message":"L'e-mail est déjà utilisé","error":"Doublon","statusCode":409}
GET /api/exceptions/liste → 400 {"message":["nom trop court","e-mail invalide"],"error":"Bad Request","statusCode":400}
GET /api/exceptions/objet → 422 {"code":"GROUPE_COMPLET","message":"Le groupe DEV101 est complet","places":0}
GET /api/exceptions/generique → 429 {"statusCode":429,"message":"Trop de requêtes, patientez"}
GET /api/exceptions/interdit → 403 {"message":"Forbidden","statusCode":403}
GET /api/exceptions/metier/7 → 404 {"statusCode":404,"code":"STAGIAIRE_INTROUVABLE","message":"Stagiaire 7 introuvable"}
GET /api/exceptions/bug → 500 {"statusCode":500,"message":"Internal server error"}
GET /api/exceptions/erreur → 500 {"statusCode":500,"message":"Internal server error"}
Lecture des réponses
ÉcritureCorps obtenu
new NotFoundException()message par défaut (Not Found), sans champ error
new NotFoundException('…')message personnalisé + error (nom du statut) + statusCode: la forme la plus courante
new ConflictException('…', { description: 'Doublon' })la description remplace le texte du champ error
new BadRequestException([…])message est un tableau (la forme utilisée par le ValidationPipe)
new UnprocessableEntityException({ … })l'objet remplace entièrement le corps : statusCode disparaît s'il n'est pas inclus
new HttpException('…', 429)pour un statut sans classe dédiée
throw new StagiaireIntrouvableException(7)votre format, défini une fois et réutilisé partout
une erreur JavaScript (TypeError, Error)500 « Internal server error », quel que soit le message

Le masquage des erreurs 500 est une protection. Le dernier exemple contient un mot de passe dans son message : il n'apparaît pas dans la réponse. Les détails d'une erreur imprévue (chemins de fichiers, requêtes SQL, adresses internes) ne doivent jamais être envoyés au client. Ils doivent en revanche être journalisés côté serveur : c'est ce que fera notre filtre personnalisé (leçon 9.3).

Choisir le bon statut
SituationException
Données mal formées (type, format, champ manquant)BadRequestException (400)
Pas d'identification (pas de jeton, jeton invalide)UnauthorizedException (401)
Identifié, mais pas le droitForbiddenException (403)
Ressource inexistanteNotFoundException (404)
Conflit avec l'état actuel (doublon, déjà terminée)ConflictException (409)
Données bien formées mais refusées par une règle métier (groupe complet)UnprocessableEntityException (422)
Service dépendant indisponible, maintenanceServiceUnavailableException (503)

Le choix entre 409 et 422 pour une règle métier varie selon les équipes ; l'important est d'être cohérent dans toute l'API et de le documenter.

L'option cause

Quand vous transformez une erreur technique en exception HTTP, conservez l'erreur d'origine avec cause: elle n'est pas envoyée au client mais reste disponible pour le journal.

try {
  return await this.calendrier.joursFeries(annee);
} catch (erreur) {
  throw new ServiceUnavailableException('Calendrier indisponible', { cause: erreur });
}
Activités

Activité 1 Le bon statut

Quelle exception lever ? (a) Un formateur tente de supprimer une note alors que seul l'administrateur le peut. (b) On demande le stagiaire 9999. (c) On inscrit un stagiaire dans un groupe déjà complet. (d) Le corps contient "age": "vingt". (e) La requête n'a pas de clé API. (f) On crée un groupe dont le code existe déjà.

Voir le corrigé

(a) 403 ForbiddenException. (b) 404 NotFoundException. (c) 422 (ou 409, selon la convention de l'API). (d) 400 BadRequestException (en pratique levée par le ValidationPipe). (e) 401 UnauthorizedException. (f) 409 ConflictException.

Activité 2 Une exception métier

Créez GroupeCompletException (statut 422) qui reçoit le code du groupe et sa capacité, et produit { statusCode: 422, code: 'GROUPE_COMPLET', message: 'Le groupe DEV101 est complet (20 places)', capacite: 20 }.

Voir le corrigé
export class GroupeCompletException extends HttpException {
  constructor(groupe: string, capacite: number) {
    super(
      { statusCode: HttpStatus.UNPROCESSABLE_ENTITY, code: 'GROUPE_COMPLET', message: `Le groupe ${groupe} est complet (${capacite} places)`, capacite },
      HttpStatus.UNPROCESSABLE_ENTITY,
    );
  }
}

On peut aussi hériter de UnprocessableEntityException et appeler super({ … }). Le champ code est très utile au client : il peut traiter l'erreur sans analyser le texte du message.

Activité 3 Erreur 500 ou 400 ?

Dans un service, findOne(id) fait return this.stagiaires.find((s) => s.id === id).nom. Que reçoit le client pour un identifiant inexistant ? Corrigez.

Voir le corrigé

find() renvoie undefined; lire .nom lève une TypeError, et le client reçoit 500 « Internal server error » au lieu d'un 404. Correction : const s = this.stagiaires.find(…); if (!s) throw new NotFoundException(`Stagiaire ${id} introuvable`); return s.nom;. Un 500 signale toujours un bug ou une panne, jamais une erreur du client.

Activité 4 Lever ou renvoyer ?

Un étudiant écrit return new NotFoundException('introuvable') au lieu de throw. Que reçoit le client ?

Voir le corrigé

Un statut 200 avec, comme corps, l'objet exception sérialisé en JSON : le client croit que tout s'est bien passé. Une exception doit être levée (throw), jamais renvoyée.

À retenir

  • Le filtre par défaut transforme une HttpException en réponse avec son statut et son contenu.
  • Message seul, description, tableau ou objet complet : l'objet remplace tout le corps.
  • Toute autre erreur devient 500 « Internal server error » : le détail est masqué au client.
  • Choisir le statut avec soin (400, 401, 403, 404, 409, 422, 503) et rester cohérent.
  • Créer des exceptions métier réutilisables avec un code exploitable par le client.
  • Toujours throw, jamais return d'une exception.

Cet article vous a-t-il aidé ?