Les codes de statut HTTP sont les nombres à trois chiffres qu'un serveur place en tête de chaque réponse pour résumer ce qu'il s'est passé. C'est grâce à eux que les navigateurs, clients, proxys et CDN savent s'ils doivent mettre en cache, rediriger, réessayer ou afficher une erreur à l'utilisateur.
Chaque code appartient à l'une des cinq classes définies par son premier chiffre : 1xx informationnel, 2xx succès, 3xx redirection, 4xx erreur côté client, 5xx erreur côté serveur. Une fois la classe identifiée, on devine généralement le sens global avant même de chercher le code précis.
La plupart des applis n'utilisent qu'un noyau réduit (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503). Bien comprendre ce que chacun *signifie* - et savoir distinguer 401 Unauthorized de 403 Forbidden, ou 301 Moved Permanently de 302 Found - c'est ce qui fait la différence entre un dev backend correct et un dev backend solide.
Ce que vous allez apprendre avec cette référence
Le premier chiffre donne toujours la classe : 1xx info, 2xx succès, 3xx redirection, 4xx erreur client, 5xx erreur serveur.
Les codes de statut font *partie du contrat* d'une API - les clients doivent s'appuyer dessus pour brancher leur logique, pas parser un message d'erreur dans le corps.
4xx veut dire que le client a fait quelque chose de travers (mauvaise entrée, auth manquante, ressource inexistante). 5xx veut dire que le serveur a planté, peu importe ce que le client a envoyé.
Comment utiliser la référence pas à pas
1
Cherchez par code ou par mot-clé
Tapez un nombre (404, 429) ou un mot-clé (auth, redirect, rate limit) et la liste se filtre en direct.
2
Filtrez par classe
Utilisez les puces de classe (1xx, 2xx, 3xx, 4xx, 5xx) pour réduire la liste quand vous explorez plutôt que vous ne cherchez précisément.
3
Lisez l'explication en clair
Chaque entrée précise quand le code est renvoyé, comment le client réagit en général, et la cause la plus fréquente.
4
Comparez les codes proches
Suivez les liens « voir aussi » entre les paires piégeuses (401 vs 403, 301 vs 302) pour choisir le bon code dans votre API.
Les classes de codes de statut HTTP
Les cinq classes de codes HTTP et leur signification d'un coup d'œil. Définies par la RFC 9110 et enregistrées dans le registre IANA des codes HTTP.
Classe
Signification
Codes courants
1xx Informationnel
Requête reçue, traitement en cours
100, 101, 103
2xx Succès
La requête a fonctionné
200, 201, 204, 206
3xx Redirection
Va voir ailleurs
301, 302, 304, 307, 308
4xx Erreur client
Quelque chose cloche dans la requête
400, 401, 403, 404, 409, 422, 429
5xx Erreur serveur
Le serveur n'a pas réussi à traiter une requête pourtant valide
Succès, mais sans corps. Fréquent après un DELETE ou un PUT qui n'a rien à renvoyer.
Tous les trois sont des codes de succès - la différence porte sur ce que la réponse transporte. 201 doit inclure un en-tête Location qui pointe vers la nouvelle ressource ; 204 est vide par définition.
Redirection temporaire. Les navigateurs revérifient l'URL d'origine à chaque requête ; les favoris restent sur l'ancienne URL.
Utilisez 301 quand vous avez réellement déplacé une ressource (changement de marque, refonte d'URL). Utilisez 302 pour des redirections de courte durée : tests A/B, redirection après login, page de maintenance.
Gateway timeout - un proxy a bien atteint le serveur en amont mais n'a pas reçu de réponse à temps.
Les quatre sont des erreurs serveur, mais elles racontent des histoires très différentes au moment du debug. 500 pointe vers votre appli ; 502 et 504 vers le chemin réseau ; 503 vers la capacité.
Erreurs fréquentes avec les codes de statut
Renvoyer 200 OK avec {"error": "..."} dans le corps. Les codes de statut font partie du contrat - utilisez le bon (400, 404, 500) pour que les clients puissent brancher dessus.
Utiliser 401 pour des erreurs de permission. 401 concerne l'authentification ; un refus de permission, c'est 403.
Renvoyer 200 pour une ressource fraîchement créée au lieu de 201 accompagné d'un en-tête Location.
FAQ sur les codes de statut HTTP
Que veut dire HTTP 404 ?
404 Not Found signifie que le serveur a bien compris la requête, mais qu'aucune ressource n'existe à cette URL. La cause la plus fréquente : un mauvais chemin, une ressource supprimée ou une URL mal tapée.
Quelle est la différence entre 401 et 403 ?
401 Unauthorized veut dire que vous n'êtes pas authentifié - le serveur ne sait pas qui vous êtes. 403 Forbidden veut dire que vous êtes authentifié mais que vous n'avez pas la permission d'accéder à la ressource. Envoyer d'autres identifiants peut résoudre un 401 ; ça ne corrigera pas un 403.
Quelle est la différence entre 301 et 302 ?
301 Moved Permanently est une redirection permanente - navigateurs et moteurs de recherche mettent à jour leurs références. 302 Found est une redirection temporaire - les clients continuent à interroger l'URL d'origine. Utilisez 301 pour un déménagement définitif, 302 pour un détour temporaire.
Que veut dire HTTP 500 ?
500 Internal Server Error est une erreur générique côté serveur, levée la plupart du temps quand une exception non gérée remonte jusqu'en haut. Le client n'a rien fait de mal - c'est votre serveur qui a échoué à traiter une requête pourtant valide.
Faut-il toujours utiliser un code de statut précis ?
Oui. Renvoyer un 200 OK générique pour des erreurs, ou un 500 à toutes les sauces, rend l'API pénible à utiliser. Choisissez le code le plus précis qui colle à la situation - clients, proxys, monitoring et logique de retry s'appuient tous sur le code de statut.
Que veut dire HTTP 429 ?
429 Too Many Requests est renvoyé quand un client a atteint une limite de débit. La réponse devrait inclure un en-tête Retry-After indiquant au client à partir de quand il peut réessayer sans risque.
