À propos de ce cours
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 ».
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
| Écriture | Corps 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
| Situation | Exception |
|---|---|
| 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 droit | ForbiddenException (403) |
| Ressource inexistante | NotFoundException (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, maintenance | ServiceUnavailableException (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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !