Formations — 1 037 leçons en français

Accueil › Node.js › Codes de statut et format d'erreur

Codes de statut et format d'erreur

Concevoir une API RESTdebutant

Le code de statut est lu par des machines : un équilibreur de charge, un cache, une bibliothèque de réessai. Le corps est lu par des humains et par le code du client. Les deux ont des règles différentes.

Le premier chiffre décide

Classe Sens Le client doit
2xx réussi continuer
4xx la requête est fautive corriger, pas réessayer
5xx le serveur a échoué réessayer plus tard

C'est la seule distinction qu'une bibliothèque de réessai regarde. Se tromper de classe fait réessayer une requête invalide à l'infini, ou abandonner une panne passagère.

Les codes qu'on utilise vraiment

200  lu, modifié
201  créé            → en-tête Location
204  fait, rien à dire (DELETE)
400  corps illisible
401  non authentifié  → identifiez-vous
403  authentifié, pas le droit
404  n'existe pas
409  conflit d'état   (déjà annulée, doublon)
422  corps valide, contenu invalide
429  trop de requêtes → en-tête Retry-After
500  bogue côté serveur
503  dépendance indisponible

Un seul format, pour toute l'API

{
  "erreur": {
    "code": "solde_insuffisant",
    "message": "Le solde du compte ne couvre pas ce paiement.",
    "details": [{ "champ": "montant", "probleme": "max 4990" }]
  }
}

Le code est stable : le client s'en sert pour décider. Le message est humain et peut changer. Sans code, les clients analysent le message — et une correction d'orthographe casse leur intégration.

Les termes à connaître

Classe de statut

Le premier chiffre suffit à décider quoi faire : 2xx réussi, 3xx ailleurs, 4xx la requête est fautive, 5xx le serveur a échoué.

400 contre 422

400 pour un corps qu'on ne sait pas lire, 422 pour un corps bien formé dont le contenu est invalide. Le choix doit être le même partout.

401 contre 403

401 — on ne sait pas qui vous êtes, authentifiez-vous. 403 — on le sait, et vous n'avez pas le droit. Se réauthentifier ne changera rien au second.

Code machine

Une chaîne stable comme solde_insuffisant, destinée au code du client. Elle survit aux traductions et aux reformulations du message.

Message humain

Une phrase lisible, destinée à un développeur ou à un journal. Elle peut changer à tout moment — donc aucun client ne doit l'analyser.

Format d'erreur unique

Une seule forme de corps d'erreur pour toute l'API. Sans elle, chaque client écrit un analyseur par point d'entrée.

Fuite d'information

Un message d'erreur qui révèle une requête SQL, un chemin de fichier ou l'existence d'un compte. Les détails internes restent dans le journal.

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.