Codes de statut HTTP : 200, 201, 400, 401, 403, 404, 500

Un code de statut HTTP est le nombre à trois chiffres que le serveur place en tête de chaque réponse pour dire ce qui s'est passé : 200 pour une réussite, 404 pour une ressource introuvable, 500 pour une panne du serveur. Le premier chiffre donne la famille (succès, redirection, erreur du client, erreur du serveur). Ce chapitre présente les codes qu'une API utilise vraiment, comment choisir entre des codes voisins (401, 403 et 404 ; 400 et 422) et les erreurs de choix les plus fréquentes.

Cinq familles

La distinction entre 4xx et 5xx est la plus importante : elle dit de quel côté est le problème. Un client qui reçoit 400 sait que renvoyer la même requête ne servira à rien ; un client qui reçoit 503 peut réessayer plus tard.

Les codes de succès (2xx)

Une liste vide est une réussite : GET /v1/fiches?etat=VA qui ne trouve aucune fiche validée renvoie 200 avec une liste vide ([]), pas 404. La collection existe ; elle ne contient simplement rien qui corresponde au filtre.

Les redirections (3xx)

Une API redirige rarement, mais deux cas arrivent :

• 304 Not Modified répond à une requête conditionnelle (If-None-Match) : la copie du client est toujours à jour (chapitre 2) ;
• 308 Permanent Redirect et 307 Temporary Redirect déplacent une ressource en conservant la méthode et le corps. Leurs ancêtres 301 et 302 autorisent historiquement le client à transformer un POST en GET lors de la redirection, ce qui fait perdre le corps. Pour une API, préfère 308 et 307.

Les erreurs du client (4xx)

Les erreurs du serveur (5xx)

401, 403 ou 404 ?

C'est la question d'examen la plus fréquente sur les API. Pose-toi les questions dans l'ordre :

1. Le serveur sait-il qui fait la requête ? Pas de jeton, jeton expiré, signature fausse, clé d'API inconnue : 401 Unauthorized. Le nom du code est trompeur, il signifie en réalité « non authentifié ».
2. Le client a-t-il le droit de faire cette action sur cette ressource ? Le visiteur est bien identifié mais veut valider une fiche (réservé aux comptables) : 403 Forbidden.
3. La ressource existe-t-elle ? GET /v1/fiches/999 alors que la fiche 999 n'existe pas : 404 Not Found.

Un cas mérite réflexion : Lucas demande la fiche 1188, qui existe mais appartient à une autre visiteuse. Répondre 403 est exact, mais révèle que la fiche 1188 existe : en essayant 1187, 1189, 1190…, un curieux dresse la liste des fiches. Beaucoup d'API répondent donc 404 pour une ressource qui appartient à quelqu'un d'autre : pour ce client, elle n'existe pas. Les deux réponses se défendent ; l'essentiel est que la fiche ne soit jamais renvoyée. Ce contrôle manquant est la faille n° 1 des API (BOLA, chapitre 10).

400 ou 422 ?

Les deux signalent une requête à corriger. La frontière :

• 400 Bad Request : la requête est mal formée. Le serveur ne peut même pas la lire : JSON syntaxiquement faux, paramètre ?page=abc alors qu'un nombre est attendu, en-tête obligatoire absent.
• 422 Unprocessable Content : la requête est bien formée, le JSON est valide et du bon type, mais son contenu viole une règle de validation : un mois 2026-13, un montant négatif, un champ obligatoire vide.

Toutes les API ne font pas cette distinction : beaucoup renvoient 400 pour tout problème de saisie, et ce n'est pas faux. Ce qui compte, c'est la cohérence dans toute l'API, et un corps d'erreur qui dit précisément quel champ pose problème.

Et 409 ? Il ne concerne pas le format mais l'état : la fiche d'octobre est valide en soi, mais elle existe déjà ; la demande de clôture est bien formée, mais la fiche est déjà validée. Les données seraient acceptables dans un autre contexte.

L'ordre de l'arbre suit l'ordre des contrôles dans le code : on authentifie d'abord (sinon on ne sait pas quoi vérifier), on lit la requête, on cherche la ressource, on vérifie les droits, on valide les données, puis on applique les règles de gestion. Quand la ressource appartient à un autre client, l'API peut fusionner les questions 3 et 4 et répondre 404, comme expliqué plus haut.

Les libellés ne comptent pas

Le libellé qui suit le code (OK, Not Found) est un texte destiné aux humains ; les programmes l'ignorent, et HTTP/2 ne le transmet même plus. Il a d'ailleurs changé pour deux codes avec la RFC 9110 : 413 s'appelle désormais Content Too Large (anciennement Payload Too Large) et 422 Unprocessable Content (anciennement Unprocessable Entity). Beaucoup de serveurs affichent encore les anciens libellés : Node.js répond HTTP/1.1 422 Unprocessable Entity. C'est sans conséquence.

Les erreurs de choix les plus fréquentes

Exercices

09:14:02 203.0.113.50 GET /v1/fiches/1180 200
09:14:02 203.0.113.50 GET /v1/fiches/1181 404
09:14:03 203.0.113.50 GET /v1/fiches/1182 200
09:14:03 203.0.113.50 GET /v1/fiches/1183 200
09:14:03 203.0.113.50 GET /v1/fiches/1184 200
09:14:04 203.0.113.50 GET /v1/fiches/1185 429
09:31:47 198.51.100.7 POST /v1/fiches 502