Codes HTTP : ce que les tutos t'expliquent mal, et les codes que tu n'utilises jamais

Le vrai blocage n'est pas la mémoire

Un développeur junior, une personne en reconversion ou un curieux qui découvre les API n'a aucun mal à apprendre par cœur une liste de vingt codes. La mémoire n'est pas le sujet. Le sujet arrive au moment de trancher, quand deux codes semblent convenir et qu'il faut en choisir un seul.

Prends une API d'inscription à un webinaire. Un visiteur envoie un formulaire avec une adresse e-mail mal formée. Beaucoup de projets juniors renvoient un 400, d'autres un 200 avec un message d'erreur caché dans le corps de la réponse, quelques-uns un 500 parce que le code a planté avant même de vérifier quoi que ce soit. Trois réponses différentes pour une seule situation, et une seule est correcte.

Ce flou se paie à deux endroits. En entretien technique, on te tend rarement un algorithme de tri, mais on te demande souvent comment tu structurerais les réponses d'une API, et là ta connaissance des codes se voit tout de suite. En production, un mauvais code envoie ton équipe chercher un bug côté serveur alors qu'il vient du client, ou l'inverse.

La bonne nouvelle, c'est qu'il existe une logique derrière ces numéros. Une fois cette logique posée, tu n'as plus besoin de la liste. Tu déduis le bon code à partir de la situation.

Le premier chiffre est un verdict

Un code HTTP tient sur trois chiffres, et le premier porte l'essentiel du message. Il répond à une question simple : est-ce que ça a marché, et si non, à qui la faute ? Les deux chiffres suivants ajoutent le détail, mais le verdict tient dans le premier.

Voici les cinq familles et ce que chacune signale.

• 1xx, information. Le serveur accuse réception et la requête continue. Tu les croises peu au quotidien, sauf 101 lors d'un passage en WebSocket.
• 2xx, succès. La requête a abouti. 200 pour un résultat classique, 201 quand une ressource vient d'être créée, 204 quand tout s'est bien passé mais qu'il n'y a rien à renvoyer.
• 3xx, redirection. La ressource est ailleurs, ou n'a pas changé depuis la dernière fois. Le client doit suivre une piste au lieu de recevoir directement le contenu.
• 4xx, erreur côté client. La requête elle-même pose problème. Mauvaise adresse, données invalides, absence d'authentification. Rejouer la même requête à l'identique produira la même erreur.
• 5xx, erreur côté serveur. La requête était acceptable, mais le serveur n'a pas su la traiter. Là, une nouvelle tentative un peu plus tard a des chances d'aboutir.

Cette distinction entre 4xx et 5xx est celle qui change ta façon de travailler. Face à un 4xx, inutile de relancer la requête telle quelle, il faut la corriger. Face à un 5xx, une nouvelle tentative espacée dans le temps a du sens, avec un délai qui augmente à chaque essai pour ne pas assommer un serveur déjà en difficulté. Cette mécanique porte un nom que tu retrouveras dans toutes les librairies HTTP sérieuses : le backoff exponentiel.

Toute la suite de l'article n'est qu'une application de ce principe à des cas où deux codes de la même famille se disputent la même réponse.

Les cas où tout le monde hésite

401 contre 403 : identité contre permission

C'est la confusion la plus répandue, et la plus facile à lever avec une phrase. Le 401 concerne l'identité : le serveur ne sait pas qui tu es. Le 403 concerne les droits : le serveur sait qui tu es, mais tu n'as pas le droit d'accéder à cette ressource.

Une requête sans jeton d'authentification sur une zone protégée donne un 401.

GET /api/factures HTTP/1.1
Host: exemple.fr
 
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

La même requête, cette fois avec un jeton valide mais issu d'un compte sans les droits nécessaires, donne un 403.

GET /api/admin/utilisateurs HTTP/1.1
Authorization: Bearer <jeton valide, compte standard>
 
HTTP/1.1 403 Forbidden

Le nom officiel du 401 entretient la confusion, puisqu'il s'appelle "Unauthorized" alors qu'il parle d'authentification. Retiens le sens réel, pas l'étiquette. Cette distinction touche directement la sécurité de tes projets, un terrain où les erreurs sont fréquentes, comme le détaille notre article sur les failles de sécurité des projets juniors.

301, 302, 307, 308 : la redirection a des conséquences

Une infographie résume souvent les redirections à "301 permanent, 302 temporaire". C'est vrai, mais incomplet, et l'incomplétude se paie. Le 301 annonce un déplacement définitif, le 302 un déplacement provisoire. Jusque-là, rien de piégeux.

Le détail qui manque touche la méthode HTTP. Historiquement, un navigateur qui suivait un 301 ou un 302 pouvait transformer un POST en GET au passage, ce qui casse une soumission de formulaire de façon silencieuse. Les codes 307 et 308 ont été introduits pour lever cette ambiguïté : ils préservent la méthode d'origine. Un 308 est un 301 qui garde le POST, un 307 est un 302 qui fait de même.

Deux conséquences pratiques valent d'être connues. Côté référencement, un 301 transmet la valeur de l'ancienne adresse vers la nouvelle, là où un 302 la garde sur l'ancienne, ce qui explique pourquoi un mauvais choix peut faire stagner un site dans les résultats de recherche. Côté navigateur, un 301 est mis en cache de façon durable : une fois qu'un navigateur a retenu la redirection, il ne repasse plus par l'ancienne adresse, et corriger une erreur de 301 posée en production tient parfois du casse-tête.

Les codes que tu n'utilises pas, et qui te feraient remarquer

Beaucoup d'API juniors se limitent à 200, 404 et 500. Elles fonctionnent, mais elles passent à côté de codes qui rendent une API lisible pour ceux qui la consomment. En voici quatre qui reviennent tout le temps une fois qu'on travaille sur des API réelles.

• 422, contenu non traitable. La requête est bien formée, sa syntaxe est correcte, mais les données ne passent pas la validation métier. Un e-mail au mauvais format, un âge négatif. Le 400 signale une requête malformée, le 422 signale une requête compréhensible mais refusée sur le fond. La frontière entre les deux reste discutée, et beaucoup d'API réservent le 422 aux erreurs de validation explicites.
• 429, trop de requêtes. Un client dépasse la limite d'appels autorisée sur une période donnée. Ce code s'accompagne d'un en-tête Retry-After qui indique au client combien de temps patienter avant de réessayer.
• 409, conflit. La requête entre en collision avec l'état actuel de la ressource. Tentative de créer un compte avec un e-mail déjà pris, mise à jour d'un document dont la version a changé entre-temps.
• 202, accepté. La requête est prise en compte mais son traitement se fera plus tard, en tâche de fond. Utile pour tout ce qui est asynchrone, comme l'envoi d'un lot d'e-mails ou la génération d'un export lourd.

Un exemple de validation refusée avec un 422 :

POST /api/inscriptions
{ "email": "pasunemail", "age": -3 }
 
HTTP/1.1 422 Unprocessable Content
{ "erreurs": { "email": "format invalide", "age": "doit etre positif" } }

Ces codes ne sont pas de la décoration. Une API qui répond 429 avec un délai clair, 409 sur un doublon et 202 sur une tâche longue est une API dans laquelle un autre développeur se repère sans lire la documentation. Si tu construis tes premières API, ces distinctions font partie du programme de nos formations pour créer une API REST avec Python et FastAPI ou développer des API REST en Java avec Spring Boot.

502, 503, 504 : lire l'infrastructure

Ces trois codes racontent souvent la même chose vue sous des angles différents, et savoir les distinguer t'oriente vers le bon endroit dans une infrastructure. Un 502 Bad Gateway signale qu'un intermédiaire, comme un reverse proxy ou un load balancer, a reçu une réponse invalide du serveur situé derrière lui. Un 504 Gateway Timeout dit que ce même intermédiaire a attendu trop longtemps une réponse qui n'est jamais venue. Un 503 Service Unavailable annonce une indisponibilité volontaire et temporaire, maintenance planifiée ou surcharge assumée, souvent avec un en-tête Retry-After.

La nuance entre 429 et 503 mérite d'être posée, car elles se ressemblent. Le 429 vise un client précis qui a trop tapé et qu'on ralentit individuellement. Le 503 vise tout le monde, parce que le service entier est indisponible. Cette lecture prend son sens dès que tu déploies derrière un proxy, un sujet couvert dans notre formation Docker pour développeurs web.

Les pièges qui coûtent cher en production

Renvoyer 200 avec une erreur dans le corps

C'est l'une des pires habitudes qu'on prenne en début de carrière. L'API répond systématiquement 200, et glisse un champ { "erreur": "..." } dans le corps quand quelque chose tourne mal. Le problème dépasse la simple élégance. Ta supervision, tes outils de cache et les clients qui appellent ton API se fient au code pour savoir si la requête a réussi. En répondant 200 sur une erreur, tu leur mens, et une panne réelle passe inaperçue dans les tableaux de bord.

Le cache silencieux du 301

Poser un 301 par erreur, puis vouloir revenir en arrière, réserve une mauvaise surprise. Les navigateurs retiennent cette redirection définitive de façon durable. Les visiteurs qui ont déjà croisé l'ancienne adresse continueront d'être redirigés, même après ta correction, jusqu'à ce que leur cache expire. Dans le doute pendant une phase de test, un 302 se corrige sans laisser de trace.

Le 500 comme tapis sous lequel on balaie tout

Un 500 devrait signaler une vraie défaillance imprévue du serveur, pas servir de réponse par défaut à toutes les situations non gérées. Quand une validation échoue, c'est un 422 ou un 400. Quand une ressource manque, c'est un 404. Réserver le 500 aux cas où le code a réellement planté rend tes logs exploitables, parce que chaque 500 devient un incident à examiner plutôt qu'un bruit de fond permanent.

Confondre 401 et 403 en révélant trop d'informations

Sur certaines ressources sensibles, répondre 403 revient à confirmer qu'une ressource existe, simplement que le visiteur n'y a pas droit. Dans les contextes où cette existence doit rester secrète, renvoyer un 404 plutôt qu'un 403 évite de donner une information à un attaquant. Ce choix se discute au cas par cas, mais il montre qu'un code de statut n'est pas neutre, il communique. Ces subtilités reviennent souvent en entretien technique junior, où on cherche moins la récitation que la capacité à raisonner sur un cas.

Questions fréquentes