Codes de statut HTTP, gratuit

Une norme et trois décennies de dérive

Les codes de statut HTTP ont traversé plusieurs générations de spécifications. La RFC 1945 (mai 1996) a normalisé HTTP/1.0 avec les catégories de base 1xx-5xx. La RFC 2616 (juin 1999) a livré HTTP/1.1 et a été la référence canonique pendant plus d'une décennie. La série 7230-7235 (juin 2014) a scindé HTTP/1.1 en plusieurs spécifications par thème. La norme consolidée actuelle est la RFC 9110 « HTTP Semantics » (juin 2022), qui rend obsolète la scission 7230-7235 et constitue la bonne référence pour les travaux modernes. Le registre complet et à jour des codes attribués se trouve au registre des codes de statut HTTP de l'IANA.

Les cinq catégories en un coup d'œil

• 1xx Information : réponse provisoire. La requête a été reçue et le serveur continue de la traiter. Rare en pratique ; utile pour les mises à niveau de protocole et le moderne 103 Early Hints (qui permet aux serveurs de précharger les ressources critiques avant que la réponse complète ne soit prête).
• 2xx Succès : la requête a été reçue, comprise et acceptée. 200 OK est le cas quotidien ; 201 Created pour la création de ressource ; 204 No Content pour les actions réussies sans rien à renvoyer.
• 3xx Redirection : action supplémentaire requise. Les redirections classiques (301 Moved Permanently, 302 Found, 307 Temporary Redirect, 308 Permanent Redirect) plus 304 Not Modified pour la validation du cache.
• 4xx Erreur client : le client a fait quelque chose de mal : mauvaise syntaxe, authentification manquante, demande de quelque chose qui n'existe pas. La plus grande catégorie dans le trafic réel.
• 5xx Erreur serveur : le serveur a déraillé. La requête était valide ; le serveur n'a simplement pas pu répondre. Ce sont ceux qui réveillent les ingénieurs d'astreinte.

Les comparaisons « vs » qui font trébucher tout le monde

401 contre 403. La paire la plus confondue. 401 Unauthorized signifie « vous ne vous êtes pas authentifié, essayez de vous connecter » (le nom est techniquement trompeur : il s'agit d'authentification, pas d'autorisation). 403 Forbidden signifie « vous êtes authentifié, mais vous n'avez pas le droit de faire cette chose » : vos identifiants sont valides mais ne donnent pas accès à cette ressource. Un mauvais usage courant : renvoyer 403 pour des requêtes non authentifiées alors que 401 avec un en-tête WWW-Authenticate est correct.

301 contre 302 contre 307 contre 308. Deux axes : permanent contre temporaire, et le comportement de préservation de méthode :

Si vous redirigez des requêtes GET à des fins de SEO, 301 est le choix conventionnel. Si vous redirigez des requêtes POST ou PUT et voulez préserver la méthode, il vous faut 307 ou 308.

400 contre 422. 400 Bad Request concerne les requêtes syntaxiquement mal formées : JSON invalide, en-têtes requis manquants, paramètres de requête mal formés. 422 Unprocessable Entity (à l'origine un code WebDAV, largement adopté par les API REST) concerne les requêtes syntaxiquement valides présentant des problèmes sémantiques : le JSON s'analyse correctement, mais les valeurs échouent à la validation métier (quantité négative sur une commande, e-mail déjà utilisé). De nombreuses API utilisent les deux.

502 contre 503 contre 504. Trois modes de défaillance amont différents :

• 502 Bad Gateway : le proxy / la passerelle a reçu une réponse invalide du serveur amont.
• 503 Service Unavailable : le serveur est surchargé ou en maintenance. Souvent associé à un en-tête Retry-After.
• 504 Gateway Timeout : le serveur amont n'a pas répondu à temps.

404 contre 410. 404 Not Found signifie « nous ne savons pas si cela existe ou non ». 410 Gone signifie « cela existait, c'est définitivement supprimé ». Impact SEO : Google traite 410 comme un signal plus fort indiquant que le contenu est définitivement indisponible et le retire de l'index plus vite qu'il ne le fait pour 404.

Conventions des API REST

Les API REST modernes ont convergé vers un ensemble assez cohérent de conventions sur la signification des codes de statut selon les actions :

Implications pour le SEO

• 200 OK : Google indexe la page normalement.
• 301 Moved Permanently : Google met à jour l'URL indexée vers la nouvelle et transfère les signaux de classement.
• 302 Found / 307 Temporary Redirect : Google garde l'URL d'origine indexée ; le classement reste avec l'original.
• 308 Permanent Redirect : Google le traite comme un 301 : le classement est transféré.
• 304 Not Modified : utilisé par Googlebot pour les requêtes conditionnelles ; signale que le contenu en cache peut être réutilisé.
• 404 Not Found : Google retire l'URL de son index après quelques explorations.
• 410 Gone : Google retire l'URL plus vite que pour 404 ; le signal plus fort de « définitivement parti ».
• 503 Service Unavailable avec Retry-After : dit à Googlebot de revenir plus tard. À utiliser pendant les fenêtres de maintenance ; évitez d'utiliser 503 pour de véritables erreurs (Google interprète des 503 soutenus comme des instructions de ne pas explorer).
• 5xx soutenus : Google réduit la fréquence d'exploration et peut finir par retirer entièrement l'URL de l'index.

Codes célèbres et culturels

• 418 I'm a teapot : une blague de poisson d'avril issue de la RFC 2324 (Hyper Text Coffee Pot Control Protocol, 1er avril 1998). Quand l'IETF a proposé de le retirer de la spécification en 2017, la campagne « Save 418 » l'a maintenu avec succès dans les registres. Certaines API l'utilisent comme marqueur « ce n'est pas réel » ; sinon, il est inoffensif.
• 451 Unavailable For Legal Reasons : RFC 7725 (2015), nommé d'après Fahrenheit 451 de Ray Bradbury. Renvoyé lorsque le contenu est censuré par décision de justice ou demande gouvernementale.
• La série 520-527 de Cloudflare : non standard, utilisée par Cloudflare pour indiquer des échecs de connexion spécifiques au serveur amont. Courante quand un site derrière Cloudflare a des problèmes.
• Le 444 No Response de Nginx : spécifique à Nginx, renvoyé quand le serveur ferme la connexion sans envoyer aucune réponse.
• Le 420 Enhance Your Calm historique de Twitter : un code de limitation de débit depuis retiré, utilisé par l'ancienne API de Twitter ; remplacé par le 429 standard.

Erreurs courantes

1. Utiliser 200 OK pour des erreurs avec un corps d'erreur. Renvoyer {"error": "not found"} avec un statut 200 perturbe toutes les couches de cache, tous les outils de surveillance et tous les SDK client. Utilisez le bon code de statut.
2. Renvoyer 403 pour des requêtes non authentifiées. Le bon code est 401 avec un en-tête WWW-Authenticate.
3. Utiliser 302 quand vous voulez dire 301. Si le déplacement est permanent, les moteurs de recherche ont besoin du 301 pour transférer le classement. 302 garde l'ancienne URL indexée.
4. Utiliser 301 ou 302 pour les redirections POST/PUT. Historiquement, ceux-ci permettaient aux clients de changer la méthode en GET. 307 et 308 préservent strictement la méthode d'origine.
5. Renvoyer 500 alors que 503 est visé. Si le serveur est surchargé ou en maintenance, 503 avec Retry-After est le bon signal, à la fois pour les clients et pour Googlebot.
6. Utiliser 404 pour des pages définitivement supprimées. 410 Gone est le signal plus fort et est retiré des index des moteurs de recherche plus vite.
7. Oublier l'en-tête Location sur les réponses 201 et 3xx. L'en-tête Location est ce qui indique au client où se trouve la nouvelle ressource ou vers où rediriger. Sans lui, les clients ne peuvent pas naviguer.

Autres questions fréquentes

Quand devrais-je renvoyer 422 plutôt que 400 ?

400 Bad Request signifie que la requête elle-même est mal formée : JSON invalide, en-têtes requis manquants, paramètres de requête mal formés. 422 Unprocessable Entity signifie que la requête est bien formée mais contient des erreurs sémantiques qui empêchent le traitement : un champ de quantité défini sur un nombre négatif, une adresse e-mail déjà utilisée, une date dans le passé pour un champ réservé au futur. Les conventions des API REST modernes ont convergé vers cette distinction, la plupart des grandes API (GitHub, Stripe, Twilio) utilisant 422 pour les erreurs de validation.

Pourquoi Cloudflare renvoie-t-il parfois 520, 521, 522… ?

Les codes 520-527 sont spécifiques à Cloudflare, signalant différentes façons dont leur périphérie n'a pas pu joindre votre serveur d'origine. 520 est le générique « le serveur web a renvoyé une erreur inconnue » ; 521 signifie que votre origine a refusé la connexion ; 522 est un délai de connexion dépassé vers votre origine ; 524 signifie que votre origine a mis trop de temps à répondre. Ils ne figurent pas dans le registre de l'IANA, mais sont fréquemment rencontrés quand des sites derrière Cloudflare ont des problèmes de backend.

Mon navigateur me montrera-t-il quel code mon API a renvoyé ?

Oui, ouvrez les DevTools → l'onglet Réseau, cliquez sur la requête et regardez la colonne « Status ». Les navigateurs affichent aussi des pages génériques pour certains codes (le jeu du dinosaure lors des échecs de connexion de Chrome, les pages 404 / 500 standard) ; mais le code numérique réel est toujours dans la réponse.

Qu'est-ce que 103 Early Hints ?

Un code 1xx relativement nouveau (RFC 8297, 2017) qui permet au serveur d'envoyer des en-têtes Link: rel=preload avant que la réponse complète ne soit prête, indiquant au navigateur de commencer à récupérer tôt les ressources critiques (CSS, polices, images). Désormais pris en charge par Chrome et livré par Cloudflare, Fastly et d'autres CDN comme optimisation de performance.

Puis-je inventer mon propre code de statut ?

Techniquement oui : HTTP autorise n'importe quel code à 3 chiffres dans la plage 100-599. En pratique non : les clients, les proxys et les caches traitent les codes inconnus selon leur premier chiffre (donc 4xx = erreur client de façon générique, 5xx = erreur serveur). Certains fournisseurs le font (les 520 de Cloudflare, le 444 de Nginx), mais à moins de contrôler les deux extrémités du fil, tenez-vous-en au registre de l'IANA. Inventer un 299 ne cassera rien, mais ne communiquera rien non plus.

Pourquoi le « code de statut » s'appelle-t-il un « statut » et non un « code d'erreur » ?

Parce que la plupart ne sont pas des erreurs. 200 OK est le code de statut le plus renvoyé au monde : il signifie « tout s'est bien passé ». Les codes communiquent le statut de la requête : succès, redirection, erreur client, erreur serveur. Les appeler « codes d'erreur » biaise vers les cas négatifs qui sont journalisés et remarqués ; les codes de succès font leur travail silencieusement à chaque microseconde.