Chapitre 6.11Les codes HTTP

Nous venons de voir le fonctionnement du protocole HTTP, celui qui porte la communication entre les clients et les serveurs web.

Chaque réponse d'un serveur commence par un code, un simple nombre qui résume ce qui s'est passé. Ce nombre aide le client à comprendre la réponse et à décider quoi en faire.

Tu en as sûrement déjà croisé un affiché en grand sur une page, le fameux "404, page introuvable". Pour en voir d'autres, ouvre la console de ton navigateur avec la touche F12 et va dans l'onglet réseau. En cliquant sur une ligne, tu verras le détail de chaque requête et de sa réponse.

Cinq familles

Les codes sont des nombres à trois chiffres compris entre 100 et 599. Le premier chiffre donne la famille, et à lui seul il te dit déjà l'essentiel.

• 1xx : informationnel, la requête a été reçue et le traitement continue.
• 2xx : succès.
• 3xx : redirection, une action supplémentaire est nécessaire pour compléter la requête.
• 4xx : erreur côté client, c'est la demande qui pose problème.
• 5xx : erreur côté serveur, la demande était correcte mais le serveur n'a pas su répondre.

La frontière entre 4xx et 5xx est le point le plus utile à retenir, car elle désigne le responsable. Une avalanche de 4xx dans les journaux d'un site signale généralement un problème d'intégration, quelqu'un appelle mal le service. Une avalanche de 5xx signale que ton propre système va mal.

Il existe plusieurs dizaines de codes officiellement enregistrés, mais une quinzaine suffit à couvrir la quasi-totalité de ce que tu verras passer.

Les succès

• 200 OK : la requête a réussi, et la réponse contient ce qui était demandé.
• 201 Created : une ressource a été créée, typiquement un nouvel utilisateur ou une nouvelle commande. La réponse indique en général où trouver la ressource fraîchement créée.
• 202 Accepted : la requête a été acceptée mais n'est pas encore traitée. Le serveur te dit "j'ai bien reçu ta demande, je la traite dans mon coin, tu peux retourner à tes occupations". C'est le code des traitements longs, un export de données ou l'envoi d'une campagne d'emails.
• 204 No Content : la requête a réussi et il n'y a rien à renvoyer. Très courant après une suppression ou une mise à jour.

Les redirections

• 301 Moved Permanently : la ressource a déménagé définitivement. C'est indispensable quand tu changes les URL d'un site, pour rediriger vers la nouvelle page tous les liens déjà dans la nature. Ça évite de perdre les visiteurs, et ça permet surtout aux moteurs de recherche de transférer le référencement acquis vers la nouvelle adresse.
• 302 Found : la même idée, mais temporaire. Le moteur de recherche garde l'ancienne URL dans son index et repassera plus tard. Confondre les deux est une erreur classique, une redirection définitive posée en 302 fait stagner le référencement, et une redirection temporaire posée en 301 se retrouve mise en cache par les navigateurs de façon très difficile à annuler.
• 304 Not Modified : le serveur confirme au client que la version qu'il possède déjà est toujours d'actualité. Rien n'est retransmis, seul le code circule. C'est un pilier de la performance web, dans la lignée de ce que nous avons vu sur le cache.

Les erreurs du client

• 400 Bad Request : la requête est invalide. Elle est mal formée, il manque un champ, une valeur est du mauvais type.
• 401 Unauthorized : malgré son nom, il signifie que l'utilisateur n'est pas identifié. Par exemple quand tu appelles la fonctionnalité "ajouter aux favoris" sans être connecté. La réponse à ce code est d'aller se connecter, sujet creusé dans le chapitre sur l'authentification.
• 403 Forbidden : l'utilisateur est bien identifié, mais il n'a pas le droit de faire cette action. Une page réservée aux administrateurs, par exemple. Se reconnecter n'y changera rien.
• 404 Not Found : la ressource n'existe pas, ou plus.
• 405 Method Not Allowed : l'adresse existe, mais pas l'action demandée. Tu essaies de modifier une fiche client alors que le développeur n'a prévu que la création et la lecture.
• 409 Conflict : la requête n'a pas de sens d'un point de vue métier. La création d'un compte avec un email déjà utilisé en est l'illustration parfaite.
• 410 Gone : la ressource a existé et a été volontairement supprimée. C'est un 404 assumé, qui dit aux moteurs de recherche de désindexer immédiatement plutôt que de repasser pendant des mois.
• 429 Too Many Requests : tu envoies trop de requêtes, ralentis. Des limitations de ce type protègent les infrastructures contre la saturation, notamment contre les attaques par déni de service distribué (DDoS), où des pirates détournent des milliers d'objets connectés mal sécurisés, caméras de surveillance et autres babyphones, pour bombarder un site de requêtes.
  
  C'est aussi très utile pour absorber les pics de trafic légitimes. À L'Équipe, c'est par exemple ce qu'on retourne aux clients un soir de match exceptionnel du PSG.

Les erreurs du serveur

• 500 Internal Server Error : une erreur inattendue côté serveur, le plus souvent un bug. C'est le code fourre-tout, celui qui déclenche les alertes et fait sonner les téléphones.
• 502 Bad Gateway : dans les structures à fort trafic, les navigateurs ne parlent pas directement aux serveurs qui exécutent le code métier. La requête passe d'abord par un intermédiaire qui gère le cache et la sécurité. Cet intermédiaire renvoie une 502 quand le serveur qu'il protège lui a lui-même répondu n'importe quoi.
• 503 Service Unavailable : le serveur est temporairement indisponible, souvent parce qu'il est en maintenance ou surchargé. Contrairement à la 500, elle sous-entend que ça reviendra tout seul.
• 504 Gateway Timeout : la variante patience épuisée de la 502. L'intermédiaire a bien transmis la requête, mais le serveur derrière n'a jamais répondu dans le temps imparti.

Il existe un code que tu ne verras jamais en production, le 418, "je suis une théière". Il vient d'un poisson d'avril publié en 1998, la spécification d'un protocole de contrôle des cafetières par hypertexte. C'est le code qu'une théière doit renvoyer si on lui demande de préparer un café. Il a survécu à titre de blague, et on en trouve encore des traces cachées dans certains logiciels.

Pourquoi ça compte au-delà du navigateur

Jusqu'ici, chaque fois que j'ai évoqué les clients HTTP, je t'ai parlé des plus connus, les navigateurs web. Ils permettent les échanges entre une personne munie d'une interface graphique et un serveur.

Mais dans le back-end, nous construisons souvent des architectures découpées en petits morceaux qui communiquent eux aussi en HTTP. Il y a donc là aussi un client, sauf qu'il s'agit d'un programme. Ces clients spécialisés ne cherchent pas à afficher quoi que ce soit, ils transmettent la réponse au reste du logiciel.

C'est précisément pour ça que les codes sont cruciaux. Un programme ne lit pas le message d'erreur, il lit le nombre, et c'est lui qui détermine la suite. Une 404 signifie qu'il faut abandonner proprement, une 401 qu'il faut renouveler un jeton d'accès, une 503 qu'il faut patienter et réessayer dans quelques secondes, une 400 qu'il ne sert à rien de réessayer puisque c'est la demande elle-même qui est fautive.

De mon expérience, c'est le point qui différencie une intégration robuste d'une intégration fragile. Beaucoup de logiciels traitent toute réponse autre que 200 comme un échec unique et indifférencié, et se privent ainsi de toute l'information que le serveur leur a soigneusement fournie.