Pourquoi les codes de statut sont votre premier signal de diagnostic
Chaque réponse HTTP porte un code de statut à trois chiffres, et ce simple nombre est souvent le signal de diagnostic le plus rapide dont vous disposiez. Avant même d'ouvrir un fichier de logs ou un tableau de traçage, le code de statut vous dit déjà si la requête a réussi, a été redirigée, a été rejetée à cause du client, ou a échoué à cause du serveur. Savoir lire correctement les codes de statut — et les surveiller systématiquement — est l'une des habitudes les plus rentables en observabilité d'API.
Le problème est que la plupart des équipes traitent les codes de statut de façon binaire : « 200 c'est bon, tout le reste est mauvais ». Ce modèle mental passe à côté de distinctions essentielles. Un 404 sur une URL mal tapée est un bruit de fond normal d'Internet ; un 404 sur un endpoint qui fonctionnait hier est une régression. Un pic de 401 juste après une rotation de token est attendu ; le même pic à 3 h du matin sans déploiement est un incident. Ce guide détaille chaque plage de codes pour que votre surveillance puisse distinguer ces situations.
2xx Succès : ce que « ça fonctionne » signifie vraiment
200 OK est la réponse de succès par défaut, mais ce n'est pas la seule à distinguer. 201 Created confirme qu'une ressource a bien été persistée — si votre API renvoie 200 au lieu de 201 après un POST, c'est le signe que votre sémantique de réponse s'est éloignée de la convention attendue par vos clients. 204 No Content est correct pour les requêtes réussies sans contenu à renvoyer, comme un DELETE ; renvoyer un 200 avec un corps vide à la place est une incohérence fréquente mais inoffensive, qu'il vaut la peine de standardiser.
Le piège avec les codes 2xx est de supposer qu'ils prouvent la justesse de la réponse. Un 200 OK avec un corps JSON malformé ou vide reste un 2xx dans n'importe quel tableau de bord, ce qui explique pourquoi la surveillance des codes de statut seule ne suffit pas — la combiner avec des assertions de contenu permet de détecter les échecs qu'un code de statut seul ne révélera jamais.
3xx Redirections : quand le succès ne raconte pas toute l'histoire
Les redirections sont rares dans les API JSON mais courantes sur les endpoints orientés web, et elles méritent plus d'attention qu'on ne leur accorde habituellement. 301 Moved Permanently et 308 Permanent Redirect indiquent aux clients et aux moteurs de recherche de mettre à jour l'URL stockée ; si un moniteur reçoit indéfiniment un 301 sans jamais atteindre un 200 final, la chaîne de redirection est cassée ou boucle sur elle-même. 302 Found et 307 Temporary Redirect devraient se résoudre en un 2xx au saut suivant — un moniteur qui ne suit pas les redirections signalera à tort une panne pour un endpoint parfaitement sain.
304 Not Modified est un cas particulier qui mérite d'être suivi séparément : il confirme que votre couche de cache (ETags, GET conditionnel) fonctionne. Une baisse soudaine des réponses 304, remplacées par des payloads 200 complets, signifie généralement qu'un en-tête de cache a régressé lors d'un déploiement récent — un problème de performance bien avant de devenir une panne.
4xx Erreurs client : à qui la faute, vraiment ?
Les codes 4xx sont étiquetés « erreurs client », mais cette étiquette est trompeuse du point de vue de la surveillance — un pic soudain de 4xx est très souvent votre faute. Un pic de 400 Bad Request juste après un déploiement signifie généralement qu'une règle de validation a changé et que les clients existants ne s'y conforment plus. 401 Unauthorized et 403 Forbidden sont attendus de façon isolée (identifiants erronés, tokens expirés), mais un pic soudain généralisé pointe vers un service d'authentification cassé ou une passerelle mal configurée, pas vers des milliers d'utilisateurs qui se trompent soudainement de mot de passe.
404 Not Found mérite une base de référence plutôt qu'une alerte stricte — Internet est plein de scanners et de liens obsolètes. Ce qui compte, c'est la variation : si un endpoint spécifique qui renvoyait 200 se met à renvoyer 404, c'est une régression de routage, pas du bruit de fond. 429 Too Many Requests est le seul 4xx sur lequel vous devriez presque toujours alerter pour les intégrations critiques — il signifie que du trafic légitime est limité, et s'il persiste, il dégrade exactement les utilisateurs qui comptent le plus.
5xx Erreurs serveur : les codes qui devraient vous réveiller
Les codes 5xx sont sans ambiguïté : quelque chose de votre côté a échoué. 500 Internal Server Error est le fourre-tout générique — utile comme détecteur de fumée, mais il faut toujours creuser dans les logs pour trouver l'exception réelle derrière. 502 Bad Gateway signifie que votre load balancer ou reverse proxy n'a pas pu obtenir de réponse valide d'un service en amont — vérifiez la santé de ce qui se trouve derrière votre passerelle, pas la passerelle elle-même. 503 Service Unavailable indique généralement que le service refuse intentionnellement le trafic (protection contre la surcharge, mode maintenance, ou disjoncteur déclenché), tandis que 504 Gateway Timeout signifie que l'amont a mis trop de temps à répondre.
Ces trois codes — 502, 503, 504 — sont souvent confondus mais pointent vers des couches différentes de votre infrastructure, et alerter sur « 5xx » comme un seul groupe gaspille la valeur diagnostique que le code spécifique offre déjà gratuitement. Une configuration de surveillance qui affiche le code exact, et pas seulement « 5xx détecté », réduit le temps de triage de plusieurs minutes à quelques secondes.
