Watchtower Ping

Guide de dépannage pour agences et freelances

Erreur 502 Bad Gateway : que faire, dans quel ordre

Le site d'un client affiche « 502 Bad Gateway » et plus rien ne fonctionne. Ce code ne désigne pas une panne précise : il dit qu'un intermédiaire (proxy, CDN, serveur web devant PHP) n'a pas obtenu de réponse valable du serveur placé derrière lui. Voici comment trouver lequel, lire les journaux, corriger les causes fréquentes et prévenir le client. Les faits cités renvoient à la RFC 9110, à MDN, à Cloudflare, à nginx et à PHP.

Publié le 28 octobre 2026


La réponse courte

Une erreur 502 se corrige presque toujours côté serveur, pas côté visiteur. La démarche tient en six étapes :

  1. Confirmez la panne depuis l'extérieur, avec l'adresse exacte, et notez l'heure et le code renvoyé.
  2. Identifiez qui affiche la page d'erreur : le CDN (Cloudflare par exemple), le proxy ou le serveur web.
  3. Ouvrez le journal d'erreurs de cet intermédiaire : il nomme le serveur en amont qui n'a pas répondu correctement.
  4. Vérifiez que ce service amont tourne (PHP-FPM, application Node, conteneur) et redémarrez-le si besoin.
  5. Corrigez la cause : saturation, crash après une mise à jour, mauvais port ou socket, en-têtes trop gros.
  6. Revérifiez de l'extérieur, puis informez le client de ce qui s'est passé et de ce qui a été fait.

Ce que signifie vraiment un 502

La RFC 9110, qui définit la sémantique de HTTP, le formule ainsi : le code 502 indique que le serveur, agissant comme passerelle ou proxy, a reçu une réponse invalide d'un serveur entrant qu'il a contacté pour traiter la requête. Autrement dit, la page d'erreur vient d'un maillon intermédiaire, et le problème se trouve derrière lui.

MDN précise deux nuances utiles. Si le serveur d'origine renvoie une erreur HTTP valide, la passerelle doit la transmettre telle quelle plutôt qu'un 502. Et si elle ne reçoit aucune réponse à temps, elle renvoie plutôt un 504 Gateway Timeout. Un 502 signale donc le plus souvent un service amont arrêté, qui refuse la connexion, qui coupe la connexion en cours de route ou qui renvoie une réponse illisible.

Sur un site client classique, la chaîne ressemble à ceci : visiteur, éventuel CDN, serveur web (nginx ou Apache), puis l'application (PHP-FPM pour WordPress ou PrestaShop, un processus Node ou Python pour une application). Chaque flèche de cette chaîne peut produire un 502.

Qui renvoie l'erreur : CDN, proxy ou serveur

Avant de toucher quoi que ce soit, regardez la page d'erreur elle-même, et l'en-tête Server de la réponse avec curl -sI https://domaine-du-client.fr.

  • Page aux couleurs de Cloudflare. La documentation de Cloudflare est claire : une page 502 ou 504 à sa marque signifie que c'est le serveur d'origine qui a répondu par une erreur 502 ou 504. Il faut donc enquêter chez l'hébergeur, pas chez Cloudflare.
  • Page blanche sans marque Cloudflare. Selon la même documentation, le 502 vient alors de Cloudflare. Une cause citée est un problème de compression à l'origine, par exemple un contenu gzip mal formé ou un en-tête content-length incohérent. Cloudflare suggère de désactiver la compression à l'origine pour le vérifier.
  • Page « 502 Bad Gateway » avec la mention nginx. C'est nginx qui n'a pas obtenu de réponse correcte de l'application placée derrière lui : PHP-FPM, un serveur Node, un conteneur.
  • Page de l'hébergeur. Sur un hébergement mutualisé, l'hébergeur affiche souvent sa propre page. Son espace client ou sa page d'état indique parfois un incident en cours.

Si le site répond chez vous mais pas chez le client, ou l'inverse, faites un test neutre. L'outil gratuit mon site est-il en ligne ? interroge le site depuis nos serveurs en Europe et affiche le code HTTP, le temps de réponse et les redirections. MDN rappelle qu'un 502 peut aussi venir du réseau du visiteur (VPN, proxy d'entreprise, pare-feu) quand le site fonctionne pour les autres.

Les causes fréquentes

  • Le service amont est arrêté. PHP-FPM a planté, l'application Node s'est arrêtée après une erreur, le conteneur a redémarré en boucle. nginx n'arrive pas à s'y connecter et écrit dans son journal un message du type connect() failed (111: Connection refused) while connecting to upstream.
  • Mauvaise adresse, mauvais port ou mauvais socket. Sur Debian et Ubuntu, le socket de PHP-FPM porte le numéro de version (par exemple php8.2-fpm.sock) : après un changement de version de PHP, la configuration nginx peut pointer encore vers l'ancien. Même effet après une migration de serveur ou un changement de port de l'application.
  • Saturation. Le nombre de requêtes simultanées dépasse ce que le service amont accepte. Côté PHP-FPM, c'est la directive pm.max_children qui limite le nombre de requêtes servies en même temps, selon la documentation de PHP. Un pic de trafic, un robot agressif ou une extension lente suffit à remplir tous les processus.
  • Processus tué en cours de requête. Un script trop long coupé par request_terminate_timeout, ou un processus tué faute de mémoire : la connexion se ferme avant la fin de la réponse, et nginx consigne un message comme upstream prematurely closed connection.
  • En-têtes de réponse trop gros. La documentation de nginx indique que si la première partie de la réponse, qui contient les en-têtes, dépasse proxy_buffer_size, la réponse est considérée comme invalide. Des cookies très nombreux ou très longs peuvent provoquer ce cas.
  • Problème entre le CDN et l'origine. Pare-feu de l'hébergeur qui bloque les adresses du CDN, origine qui ne répond pas pour le nom de domaine demandé, compression cassée. Cloudflare demande de vérifier que l'origine répond bien pour le nom d'hôte de l'URL en erreur.

Diagnostiquer et corriger, étape par étape

  1. Noter avant d'agir. Heure exacte, URL, code, page d'erreur affichée, dernière intervention connue (mise à jour, déploiement, changement DNS). Ces éléments servent au diagnostic, au message du client et, le cas échéant, au support de l'hébergeur ou de Cloudflare, qui demande l'horodatage avec le fuseau, l'URL en erreur et le résultat de /cdn-cgi/trace.
  2. Lire le journal d'erreurs du proxy. Avec nginx, le fichier est souvent /var/log/nginx/error.log. Cherchez les lignes à l'heure de l'incident : elles mentionnent l'adresse upstream visée et la nature de l'échec (connexion refusée, connexion fermée, en-tête trop gros).
  3. Vérifier le service amont. Avec systemd, systemctl status php8.3-fpm (adaptez la version) ou le nom du service de l'application. Avec Docker, docker ps puis docker logs sur le conteneur concerné. Un service arrêté se relance, mais lisez d'abord son propre journal pour comprendre pourquoi il s'est arrêté.
  4. Comparer l'adresse configurée et l'adresse réelle. La directive fastcgi_pass ou proxy_pass de nginx doit viser exactement le socket ou le port sur lequel écoute le service (directive listen du pool PHP-FPM, port de l'application). Après correction, testez la configuration avec nginx -t puis rechargez nginx.
  5. Traiter la saturation. Le journal de PHP-FPM signale quand le pool atteint sa limite de processus. Avant d'augmenter pm.max_children, vérifiez la mémoire disponible : chaque processus en consomme. Cherchez aussi la source du pic dans le journal d'accès (une adresse ou un robot qui martèle une page) et le script lent grâce au slowlog de PHP-FPM.
  6. Remonter la dernière modification. Si le 502 suit une mise à jour d'extension, de thème ou de version de PHP, revenez à l'état précédent sur une copie ou en désactivant l'élément en cause, puis corrigez à froid. Pour un site WordPress, la procédure site WordPress hors ligne détaille l'ordre des vérifications.
  7. Sur un hébergement mutualisé. Vous n'avez pas accès à nginx ni à PHP-FPM : ouvrez un ticket avec l'heure, l'URL et le code, vérifiez la version de PHP choisie dans l'espace client et désactivez les extensions lourdes ajoutées récemment.
  8. Revérifier de l'extérieur. Relancez un test sur l'accueil et sur une page importante (panier, formulaire, espace client). Si un CDN est en place, purgez son cache si des pages d'erreur ont pu y être conservées.

Si le code n'est pas un 502 mais un 503 ou un 504, la logique reste proche, mais la cause change. Pour une panne plus large ou un symptôme flou, suivez le guide site client inaccessible : quoi faire. Si le navigateur affiche une erreur de certificat plutôt qu'un code HTTP, voyez site HTTPS inaccessible.

Prévenir le client

Un 502 se voit tout de suite : la page d'accueil, les formulaires et le paiement tombent ensemble. Mieux vaut que le client l'apprenne par vous. Un message court suffit :

  • ce qui se passe, en une phrase et sans jargon (« le serveur qui fait tourner le site ne répond plus correctement ») ;
  • depuis quand, d'après vos constats ;
  • ce que vous faites et quand vous revenez vers lui ;
  • une fois réglé : la cause, la correction, la mesure prise pour éviter une récidive.

Pour le bilan du mois, un rapport de disponibilité en marque blanche montre les incidents et leur durée, comme dans cet exemple fictif de rapport.

Détecter le prochain 502 avant le client

Beaucoup de 502 arrivent hors des heures de bureau : un pic de trafic le soir, une mise à jour automatique la nuit, un processus qui manque de mémoire le week-end. Sans contrôle extérieur, c'est le client ou ses visiteurs qui le remarquent en premier.

Watchtower Ping vérifie chaque site depuis l'extérieur, toutes les minutes, sur toutes les formules. Une erreur serveur comme un 502 fait échouer la vérification. Un échec isolé fait passer le site en état suspect ; l'e-mail d'incident part après deux échecs consécutifs, et un second e-mail signale la résolution avec la durée de l'indisponibilité. Ces alertes arrivent à l'agence, pas au client final.

Les limites sont nettes : Watchtower Ping constate l'effet sur la disponibilité HTTP, mais ne lit pas les journaux du serveur, ne redémarre aucun service et n'identifie pas la cause. Les alertes partent uniquement par e-mail. Pour organiser ces contrôles sur tous les sites, voir comment surveiller les sites de ses clients et site client en panne la nuit.

La formule Solo coûte 19 € par mois, jusqu'à 10 clients et 20 sites surveillés ; la formule Agence 49 € par mois, jusqu'à 50 clients et 200 sites. L'essai dure 14 jours, sans carte bancaire. Le détail est sur la page tarifs.

Questions fréquentes

Quelle différence entre une erreur 502 et une erreur 504 ?

Les deux viennent d'une passerelle ou d'un proxy. Le 502 signale une réponse invalide du serveur en amont, le 504 une absence de réponse dans le délai imparti. Un 504 oriente donc plutôt vers un traitement trop long, un 502 vers un service arrêté, injoignable ou qui coupe la connexion.

Le visiteur peut-il corriger une erreur 502 ?

Rarement. Recharger la page ou réessayer plus tard aide si l'incident est passager. MDN note qu'un 502 peut venir du réseau du visiteur (VPN, proxy, pare-feu) quand le site fonctionne pour les autres ; dans tous les autres cas, la correction se fait côté serveur.

Cloudflare affiche un 502 : est-ce une panne de Cloudflare ?

Pas forcément. Si la page d'erreur porte la marque Cloudflare, Cloudflare indique que l'erreur vient du serveur d'origine. Une page blanche sans marque Cloudflare signale au contraire une erreur produite par Cloudflare.

Watchtower Ping détecte-t-il une erreur 502 ?

Oui, une erreur serveur fait échouer la vérification. Après deux échecs consécutifs, l'agence reçoit un e-mail d'incident, puis un e-mail de résolution avec la durée. L'outil ne lit pas les journaux et ne corrige pas la cause.

Sources

Documentation consultée le 28 octobre 2026 :