Recherche de codes de statut HTTP

Un code de statut, c’est le verdict du serveur sur une requête, résumé en un seul nombre, et c’est souvent le chemin le plus court vers la cause d’un échec. Il vous dit où regarder : la requête que vous avez envoyée, l’application qui l’a traitée, ou quelque chose qui se trouve entre les deux. L’outil ci-dessus traduit ce nombre en réponse.

Comment ça marche

Tapez un code (503), son début (40 liste les codes 400 à 409) ou une partie de son nom (timeout, gateway), ou choisissez une classe avec les boutons. Cliquez sur une entrée pour voir ce qu’elle signifie. Pour les codes que l’on croise le plus souvent en débogage, comme 401, 404, 429, 500 et 502 à 504, le panneau précise aussi ce qui déclenche habituellement le code, comment le corriger et les codes voisins à examiner ensuite. Chaque entrée cite la RFC qui la définit, pour que vous puissiez remonter à la source quand un détail compte.

La liste couvre toutes les entrées permanentes du registre IANA des codes de statut HTTP, y compris 418, que le registre met en réserve parce que la RFC humoristique l’a rendu trop répandu pour être réattribué. Rien de ce que vous tapez ne quitte votre navigateur.

Commencer par trouver le code de statut

Les pages d’erreur cachent souvent le vrai nombre derrière un message rassurant : lisez-le donc dans la réponse elle-même.

• Navigateur. Ouvrez les outils de développement, allez dans l’onglet Réseau et rechargez la page. Chaque requête affiche son statut. Dans Chrome, filtrez avec status-code:500, ou triez la colonne pour regrouper les échecs.
• Terminal. curl -i affiche la ligne de statut et les en-têtes au-dessus du corps. Pour n’obtenir que le nombre, bien pratique dans les scripts et les health checks, jetez le corps :

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/api/orders

curl -I est tentant, mais il envoie une requête HEAD, et certains serveurs ne répondent pas à HEAD comme à GET. Quand les deux divergent, fiez-vous à la méthode qu’utilise réellement votre application.

Un ordre de diagnostic qui fait gagner du temps

Commencez par le premier chiffre. Un 4xx signifie que le serveur estime que la faute vient de la requête : vérifiez l’URL, la méthode, les identifiants et le corps avant de toucher au serveur. Un 5xx signifie que le serveur a échoué sur quelque chose qu’il aurait dû gérer, et l’explication se trouve dans ses logs, pas dans la réponse.

Demandez-vous ensuite qui l’a produit. Un 502 ou un 504 est rarement émis par votre application. Il vient du proxy, du load balancer ou du CDN placé devant elle, qui signale que l’application n’a jamais répondu correctement. L’en-tête Server et le style de la page d’erreur trahissent généralement la couche en cause. Redémarrez ou dimensionnez à la hausse le service amont, et vérifiez le timeout du proxy, avant de fouiller le code applicatif.

Méfiez-vous des codes absents du registre. Certaines briques d’infrastructure inventent les leurs. Nginx journalise 499 quand le client a raccroché avant que la réponse soit prête, et Cloudflare renvoie 520 à 526 pour des problèmes de connexion ou de TLS avec l’origine. L’outil les signale comme inconnus, et c’est précisément l’indice : consultez la documentation de l’éditeur concerné, pas la spécification HTTP.

Réessayer sans risque

Tous les échecs ne méritent pas une nouvelle tentative, et toutes les requêtes ne peuvent pas être répétées sans danger :

• 429 et 503 vous invitent à revenir plus tard. Si la réponse contient Retry-After, attendez au moins ce délai. Sinon, appliquez un backoff exponentiel avec du jitter, pour qu’une flotte de clients ne réessaie pas au même instant.
• 502 et 504 sont souvent passagers, mais ne réessayez automatiquement que si la méthode est idempotente (GET, HEAD, PUT, DELETE). Un POST parti en timeout a peut-être déjà créé la commande : réessayer à l’aveugle risque de la créer deux fois. Les clés d’idempotence existent précisément pour ce cas.
• La plupart des autres 4xx échoueront à l’identique à chaque tentative. Réessayer un 400, un 403 ou un 422 ne fait qu’ajouter de la charge. Corrigez plutôt la requête.

Pour aller plus loin

Codes de statut HTTP : référence complète explique chaque classe en profondeur, y compris la sémantique des redirections et du cache, ainsi que les paires faciles à confondre. Si vous choisissez les codes de votre propre API plutôt que de décoder ceux d’un autre, lisez Conception d’API REST. Quand un 401 implique un bearer token, le décodeur JWT montre s’il a expiré ou s’il vise la mauvaise audience, et l’encodeur d’URL repère les query strings mal échappées qui se cachent derrière bien des 400.