Erreur 500, 502, 503 : ce que chaque code veut dire

Quand un site casse, le réflexe est d'ouvrir le code. Le code d'erreur affiché est un indice plus rapide : il dit quelle couche a lâché, et les trois plus courants désignent trois réparations complètement différentes. Cinq minutes de lecture ici épargnent une heure de recherche au mauvais endroit.

Les trois codes, en un tableau

Le 504 n'est pas dans le titre et il accompagne pourtant les autres si souvent qu'il mérite sa ligne : c'est le seul des quatre qui indique une lenteur plutôt qu'un arrêt.

500 : l'application a planté

Le serveur est debout et il a répondu. C'est votre code qui n'est pas allé au bout.

Les trois causes qui reviennent le plus :

• Une erreur fatale après un déploiement : une dépendance manquante, une version de langage différente, un fichier de configuration absent.
• La base de données ne répond plus : service arrêté, connexions saturées, mot de passe changé et pas propagé.
• Le disque est plein. C'est la cause la plus sous-estimée, parce qu'elle ne ressemble à rien : les sessions ne s'écrivent plus, les journaux non plus, et l'application tombe sur des erreurs incohérentes.

Où regarder : le journal applicatif, à la minute où l'erreur est apparue. Une 500 laisse presque toujours une trace, avec un fichier et un numéro de ligne.

502 : la machine de devant a reçu une mauvaise réponse

Une 502 vient d'un proxy : Nginx, un répartiteur de charge, un CDN. Il a transmis la requête de votre visiteur au serveur situé derrière, et a reçu en retour quelque chose d'inexploitable, ou rien du tout.

Les trois causes habituelles :

• Le processus de derrière est mort ou n'a jamais démarré : PHP-FPM arrêté, un service Node planté, un conteneur qui n'est pas reparti après un déploiement.
• Le chemin de communication est faux : un socket renommé, un port changé, une adresse interne qui a bougé lors d'une mise à jour.
• Le processus a été tué faute de mémoire. Le journal système le dit, l'application non.

Où regarder : l'état du service situé derrière le proxy, avant le code.

503 : le serveur refuse, temporairement

Une 503 est une réponse volontaire : pas maintenant. Soit le site est en mode maintenance, soit le serveur est à court de capacité et refuse plutôt que de s'effondrer.

C'est la plus rassurante des trois : rien n'est cassé. C'est aussi celle qui dure le plus longtemps, parce qu'elle suit en général un pic de trafic ou une file d'attente qui ne se vide pas. Et c'est la seule qui peut être la bonne réponse : pendant une maintenance annoncée, un 503 accompagné d'un en-tête Retry-After est exactement ce qu'il faut renvoyer.

Où regarder : si un drapeau de maintenance est resté activé, puis la charge. Un mode maintenance oublié après un déploiement du vendredi est un classique absolu.

Où lire le journal, selon la pile

tail -n 100 /var/log/nginx/error.log        # Nginx, y compris les 502 et 504
tail -n 100 /var/log/apache2/error.log      # Apache
journalctl -u php8.3-fpm --since "10 min ago"   # PHP-FPM, les processus morts
tail -n 100 storage/logs/laravel.log        # l'application, pour les 500
df -h && free -m                            # disque plein, mémoire épuisée

L'ordre compte : le journal du serveur web dit quelle couche a échoué, le journal applicatif dit pourquoi. Commencer par le second quand la panne est une 502 revient à chercher une erreur dans un fichier qui n'a jamais été exécuté.

Ce qu'il faut vérifier chez l'hébergeur avant d'accuser son code

Trois choses, et elles prennent deux minutes :

• La page d'état de l'hébergeur. Une maintenance de base de données mutualisée produit des 500 chez tout le monde en même temps.
• Les quotas. Nombre de processus, mémoire par processus, connexions simultanées à la base : les dépasser produit exactement les mêmes symptômes qu'un bogue.
• Un prélèvement refusé. Un service suspendu pour impayé répond souvent par un 503, et le message d'origine est parti dans les indésirables il y a trois semaines.

Rappelez-vous surtout que personne ne vous préviendra spontanément : une page d'état verte pendant que votre site renvoie des 500 est une situation parfaitement normale du point de vue de l'hébergeur, puisque sa machine répond.

Quoi dire au client pendant ce temps

C'est le paragraphe que personne n'écrit et que tout le monde cherche. Deux lignes suffisent, et elles ne mentionnent aucun code :

Le site affiche une erreur depuis 14 h 20. Nous avons identifié d'où elle vient et nous travaillons dessus. Je vous redonne des nouvelles à 15 h.

Ne dites pas « erreur 502 », personne ne sait ce que c'est et cela donne l'impression que vous récitez. Ne promettez pas d'heure de rétablissement tant que la cause est inconnue. Et prévenez avant qu'on vous le demande : un client qui découvre la panne par lui-même retient l'incident, un client prévenu retient la réponse.

Les trois erreurs de diagnostic qui coûtent le plus de temps

Redémarrer avant de lire. Un redémarrage efface souvent la trace de ce qui a cassé : le processus mort repart, le journal recommence, et la panne revient deux heures plus tard sans que vous en sachiez davantage. Lisez d'abord, redémarrez ensuite, dans cet ordre, même quand la tentation est forte.

Croire que le code désigne le coupable. Il désigne la couche qui a signalé le problème, pas celle qui l'a causé. Une 502 renvoyée par Nginx est presque toujours un problème PHP, et une 500 applicative est parfois un disque plein, donc un problème système.

Traiter un incident isolé comme une tendance. Une 502 unique à trois heures du matin, pendant une rotation de journaux, ne demande aucune action. Trois 502 dans la même journée en demandent une. La différence n'est visible que si quelque chose garde l'historique, ce qui est le vrai apport d'une surveillance sur la lecture ponctuelle d'un journal.

Ce que ces codes ne disent pas

Ils ne disent pas si le visiteur a vu la page. Un utilisateur dont le navigateur avait la page en cache n'a rien remarqué ; un autre, arrivé au même moment depuis un résultat de recherche, a vu l'erreur en plein écran. Ils ne disent pas non plus combien de personnes sont concernées : une erreur qui ne touche qu'une route précise, un formulaire de commande par exemple, peut renvoyer un volume ridicule de 500 et coûter très cher.

Ce que les trois ont en commun

Dans les trois cas, la machine est debout. Quelque chose a répondu. Cela écarte déjà le DNS, le réseau et l'hébergement, et c'est précisément ce qui rend ce code utile à lire avant toute chose.

Si rien ne répond du tout, le problème est ailleurs, et les quinze premières minutes se passent autrement.

Deux voisins méritent d'être distingués, parce qu'on les confond souvent avec cette famille. Un 404 n'est pas une panne : c'est la réponse correcte à une demande pour une page qui n'existe pas, et il se trie selon d'autres règles. Un avertissement de certificat n'est pas un code d'erreur du tout : le serveur répond parfaitement, c'est le navigateur qui refuse d'afficher, et cette panne-là ne laisse aucune trace dans vos journaux.

La question que personne ne pose

Quel que soit le code obtenu, la question utile vient après : combien de temps a-t-il été renvoyé avant que vous le sachiez ? Une 500 qui dure quatre minutes n'est pas un événement. La même 500 découverte le lendemain matin par un client est une autre histoire, et la différence n'a rien à voir avec le code.

C'est aussi la seule partie qui se chiffre : ce que coûte réellement une heure d'indisponibilité dépend beaucoup moins de la nature de la panne que du temps qu'elle a passé à l'écran.