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 :
2xxréussi,3xxailleurs,4xxla requête est fautive,5xxle serveur a échoué.- 400 contre 422
400pour un corps qu'on ne sait pas lire,422pour 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.
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.