Formations — 1 037 leçons en français

Accueil › Node.js › La gestion d'erreur centralisée

La gestion d'erreur centralisée

Express — les basesdebutant

Un gestionnaire d'erreur se reconnaît à ses quatre paramètres, et se déclare en dernier.

app.use((err, req, res, next) => {
  const statut = err.statut ?? 500;

  if (statut >= 500) {
    console.error({ correlation: req.correlation, err });   // journal complet
  }

  res.status(statut).json({
    erreur: statut >= 500 ? "erreur interne" : err.message,
    correlation: req.correlation,
  });
});

Quatre paramètres, pas trois

Express lit fn.length. Une fonction (err, req, res) est inscrite comme intergiciel ordinaire : elle recevra des requêtes normales, avec la requête dans err. Le next inutilisé est obligatoire.

Deux familles d'erreurs

Erreur attendue Erreur inattendue
Exemple ressource absente, corps invalide base injoignable, bogue
Code 400, 403, 404, 409 500
Message au client celui de l'erreur générique, toujours
Journal niveau information niveau erreur, avec la trace

Ce qui ne sort jamais du serveur

La trace d'appel et les messages de base de données. Ils nomment les chemins du serveur, le moteur, le schéma — de la reconnaissance offerte à un attaquant, et inutile au client.

Ce qui sort toujours

Un identifiant de corrélation, renvoyé dans la réponse et écrit dans le journal. Le client le cite, l'équipe retrouve la trace complète. C'est ce qui remplace le message interne sans rien perdre d'exploitable.

app.use((req, res, next) => {
  req.correlation = crypto.randomUUID();
  res.set("X-Correlation-Id", req.correlation);
  next();
});

En Express 5, le rejet d'un gestionnaire async arrive ici tout seul.

Les termes à connaître

Gestionnaire d'erreur

Un intergiciel à quatre paramètres (err, req, res, next). Express le reconnaît à fn.length, pas à son nom ni à sa position. Il se déclare en dernier, après toutes les routes.

`next(err)`

Le saut vers le gestionnaire d'erreur. Tous les intergiciels et routes ordinaires restants sont ignorés : seuls les gestionnaires à quatre paramètres sont encore essayés.

Erreur attendue

Une faute du client ou une règle métier non respectée : ressource absente, corps invalide, droits insuffisants. Elle porte son code de statut et son message est destiné au client.

Erreur inattendue

Tout le reste : une base injoignable, une propriété lue sur undefined, un bogue. Elle vaut 500, et son message ne doit jamais sortir du serveur.

Identifiant de corrélation

Un identifiant unique par requête, renvoyé au client et écrit dans le journal. Le client cite cet identifiant, l'équipe retrouve la trace complète — sans jamais avoir exposé la moindre information interne.

Trace d'appel

La pile de la fonction qui a levé. Elle expose les chemins du serveur, les noms des modules et parfois des fragments de requête. Elle appartient au journal, jamais à la réponse HTTP.

Fuite d'information

Renvoyer au client un message interne — trace d'appel, erreur de base de données, chemin de fichier. C'est une faille de reconnaissance : elle renseigne un attaquant sur la technologie, le schéma et la structure du serveur.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.