Une erreur 502 Bad Gateway signifie qu’un serveur jouant le rôle de passerelle ou de proxy a reçu une réponse invalide du serveur placé derrière lui. Le visiteur a bien atteint quelque chose, généralement nginx, Apache, un load balancer ou un CDN, mais cette couche n’a pas obtenu de réponse correcte de votre application. L’application a planté, redémarre, écoute ailleurs ou a fermé la connexion en cours de route.
Une erreur 502 concerne donc deux serveurs, pas un seul. Ce guide montre comment savoir quelle couche l’a renvoyée, comment corriger les causes habituelles et comment être prévenu de la prochaine 502 avant vos clients.
Ce que vous apprend une erreur 502
La plupart des sites web comptent au moins deux couches entre le visiteur et le code. Un CDN ou un load balancer se trouve en façade, un serveur web comme nginx termine la connexion, et un processus applicatif, comme PHP-FPM, Node.js, Gunicorn ou un serveur Java, construit la page. Chaque couche transmet la requête à la suivante et renvoie la réponse.
Une erreur 502 apparaît quand l’une de ces couches transmet une requête et ne reçoit rien d’exploitable en retour. Comparez-la aux autres erreurs de passerelle :
502 Bad Gateway : le serveur en amont a répondu quelque chose d’invalide, a réinitialisé la connexion ou l’a refusée.
503 Service Unavailable : le service est surchargé, en maintenance ou n’a aucun serveur sain vers lequel envoyer la requête.
504 Gateway Timeout : le serveur en amont n’a pas répondu à temps.
Une erreur 502 signifie donc généralement « cassé ou arrêté », une 504 généralement « trop lent ». Notre aide-mémoire des codes de statut HTTP présente le reste de la famille, et le guide sur les erreurs 503 traite de la surcharge et de la maintenance.
Trouver la couche qui a renvoyé la 502
Avant de modifier quoi que ce soit, identifiez qui a répondu. La page d’erreur et les en-têtes de réponse le disent généralement sans détour :
curl -sI https://www.example.com/checkout
HTTP/2 502
server: cloudflare
cf-ray: 8d2f1c3a5b7e4a21-ARN
server: cloudflare avec une page d’erreur Cloudflare qui nomme votre hôte : Cloudflare a joint votre origine, et c’est l’origine qui a échoué.
server: nginx ou Apache avec une page d’erreur sommaire : votre propre serveur web n’a pas pu joindre l’application placée derrière lui.
server: awselb/2.0 ou un autre load balancer : le load balancer n’a reçu de réponse valide d’aucune cible, ou de celle qu’il a choisie.
Comparez ensuite avec une requête qui contourne la couche extérieure. Envoyez-la directement à l’origine, ou au port de l’application sur le serveur lui-même :
curl -sI –resolve www.example.com:443:203.0.113.10 https://www.example.com/checkout
curl -sI http://127.0.0.1:3000/checkout
Si l’application répond en local mais pas via le proxy, examinez la configuration du proxy. Si elle ne répond pas non plus en local, le problème vient de l’application.
Causes fréquentes et solutions
Le processus applicatif a planté ou redémarre
C’est la cause la plus fréquente. Le processus derrière le proxy a manqué de mémoire, a rencontré une exception non gérée ou a été tué, et le proxy n’a plus d’interlocuteur. nginx le consigne clairement :
connect() failed (111: Connection refused) while connecting to upstream,
upstream: « http://127.0.0.1:3000/checkout »
Vérifiez si le processus tourne et pourquoi il s’est arrêté :
systemctl status myapp
journalctl -u myapp –since « 30 min ago »
dmesg -T | grep -i « killed process »
Une ligne de l’OOM killer du noyau signifie que le serveur a manqué de mémoire. Un redémarrage remet le site en ligne, mais la vraie solution consiste à ajouter de la mémoire, à réduire le nombre de workers ou à trouver et corriger une fuite. Assurez-vous que le service redémarre tout seul après un plantage, par exemple avec Restart=on-failure dans son unité systemd.
PHP-FPM est arrêté ou à court de workers
Sur les sites PHP, nginx transmet les requêtes à PHP-FPM via un socket ou un port. Si PHP-FPM est arrêté, si le chemin du socket est faux ou si les permissions du socket bloquent nginx, toutes les pages PHP renvoient une 502 :
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory)
Ce message suit généralement une mise à niveau de PHP : nginx pointe encore vers le socket de l’ancienne version. Faites pointer fastcgi_pass vers le nouveau socket et rechargez nginx. Si le log indique plutôt server reached pm.max_children, tous les workers sont occupés, souvent en attente d’une base de données lente ou d’une API externe. N’augmentez la limite que si le serveur a de la mémoire disponible ; sinon, cherchez ce qui occupe les workers.
Mauvaise adresse ou mauvais port en amont
Après une migration, la reconstruction d’un conteneur ou un changement de port, le proxy peut encore transmettre vers l’ancienne adresse. Le log d’erreurs montre l’adresse qu’il a essayée. Comparez-la avec celle où l’application écoute réellement :
ss -ltnp | grep -E ‘:(3000|8000|9000)’
Avec Docker et Kubernetes, la cause est souvent un nom de service qui ne se résout plus, un conteneur qui écoute sur 127.0.0.1 à l’intérieur du conteneur au lieu de 0.0.0.0, ou une readiness probe qui marque tous les pods comme non prêts.
Le serveur en amont a fermé la connexion trop tôt
upstream prematurely closed connection while reading response header signifie que l’application a accepté la requête puis a raccroché. Les raisons typiques : un plantage en cours de requête, un worker tué pour avoir dépassé sa propre limite de temps, comme le –timeout de Gunicorn ou le max_execution_time de PHP, et des connexions keep-alive que l’application ferme plus tôt que ne l’attend le proxy. Alignez les timeouts pour que le proxy attende un peu plus longtemps que l’application, jamais l’inverse, et repérez les requêtes assez lentes pour atteindre la limite.
En-têtes de réponse trop volumineux
Des cookies volumineux ou de nombreux en-têtes Set-Cookie peuvent dépasser le buffer de nginx prévu pour les en-têtes de réponse du serveur en amont. nginx consigne alors upstream sent too big header while reading response header from upstream et renvoie une 502. Augmentez les buffers avec prudence :
proxy_buffer_size 16k;
proxy_buffers 8 16k;
# for PHP-FPM
fastcgi_buffer_size 32k;
fastcgi_buffers 8 16k;
Cherchez ensuite pourquoi les en-têtes ont grossi. Un cookie qui grandit à chaque visite est un bug qui mérite d’être corrigé.
Le CDN n’arrive pas à joindre votre origine
Quand un CDN ou un load balancer renvoie une 502, vérifiez ce qui se trouve entre lui et votre serveur. Un pare-feu qui bloque les plages d’adresses du CDN, un certificat d’origine que le CDN n’accepte pas, une origine qui ne parle que HTTP/1.0 ou ferme les connexions trop vite, ou un enregistrement DNS qui pointe vers un ancien serveur : tout cela aboutit au même résultat. Testez l’origine directement, comme indiqué plus haut, et vérifiez le pare-feu et les réglages TLS des deux côtés.
Les erreurs 502 pendant les déploiements
Si des 502 apparaissent pendant dix ou vingt secondes à chaque fois, et toujours autour d’une mise en production, c’est le déploiement lui-même qui les provoque. L’ancien processus s’arrête, le nouveau met quelques secondes à démarrer, et toutes les requêtes entre les deux échouent. La solution : un ordre de déploiement où quelque chose est toujours prêt à répondre.
Démarrez la nouvelle version à côté de l’ancienne.
Attendez que son health check passe. Notre guide pour créer un endpoint de health check montre ce que ce contrôle doit tester.
Basculez le trafic vers la nouvelle version.
Laissez l’ancienne version terminer ses requêtes en cours, puis arrêtez-la.
Les gestionnaires de processus et les orchestrateurs le proposent sous forme de rechargements progressifs (rolling) ou sans interruption. Utilisez-les plutôt qu’un simple redémarrage.
Comment la surveillance détecte les erreurs 502
Une erreur 502 est souvent brève. Un déploiement provoque vingt secondes d’erreurs, un worker plante et redémarre, un cache masque le problème pour la plupart des visiteurs. Quand quelqu’un ouvre le site, tout fonctionne de nouveau, mais un client en plein paiement a vu l’erreur.
Un moniteur de disponibilité interroge vos pages à intervalles réguliers et enregistre le code de statut et le temps de réponse de chaque vérification. Une 502 est une vérification en échec. Ce qui compte, c’est la suite :
Confirmer l’échec. Une requête isolée en échec peut n’être qu’un incident passager. Uptimecheck vérifie jusqu’à chaque minute depuis Stockholm, Londres et New York, et confirme chaque échec depuis un second emplacement avant d’ouvrir un incident : une réinitialisation ponctuelle ne réveille personne.
Montrer les preuves. L’incident contient la réponse en échec : vous voyez le code de statut, l’en-tête server et la page d’erreur, ainsi qu’une capture d’écran de ce qu’ont vu les visiteurs. Quand le serveur n’a pas répondu du tout, vous obtenez le chemin réseau à la place.
Prévenir les bonnes personnes. Les alertes partent par e-mail, Slack, Microsoft Teams, PagerDuty, webhooks et les autres canaux d’alerte qu’utilise votre équipe.
Ne surveillez pas que la page d’accueil. Elle est souvent mise en cache par un CDN et continue de fonctionner pendant que le paiement, la connexion et l’API renvoient des 502. Ajoutez des moniteurs de disponibilité pour les pages qui rapportent de l’argent et des moniteurs d’API pour les endpoints qu’appellent vos applications. Quand la 502 vient d’une application à court de mémoire, la surveillance de serveur affiche la courbe de mémoire à côté de la panne.
Checklist erreur 502
Lisez l’en-tête server et la page d’erreur pour savoir quelle couche a renvoyé la 502.
Interrogez directement l’origine et le port de l’application pour affiner le diagnostic.
Lisez le log d’erreurs du proxy au même horodatage : connexion refusée, fermée trop tôt ou en-tête trop volumineux.
Vérifiez que le processus applicatif tourne et, sinon, pourquoi il s’est arrêté.
Comparez l’adresse, le socket et le port en amont avec ceux où l’application écoute.
Alignez les timeouts pour que le proxy attende plus longtemps que l’application.
Déployez en démarrant la nouvelle version avant d’arrêter l’ancienne.
Surveillez les pages et endpoints clés chaque minute et confirmez chaque échec avant d’alerter.