502 Bad Gateway : quelle passerelle a lâché, et comment le voir

Un 502 bad gateway n’est pas une panne vague du site. Par définition, c’est une erreur passerelle : le serveur de façade, souvent Nginx ou Apache en proxy, a interrogé un service en amont et n’a pas obtenu de réponse exploitable. Pour corriger une erreur 502, il faut donc remonter la chaîne réelle, lire le journal qui nomme l’upstream concerné, puis vérifier si le service est arrêté, saturé ou simplement trop lent.

Sur un Serveur, cette distinction évite de perdre du temps à inspecter le mauvais composant. Une erreur 502 nginx, par exemple, ne dit pas automatiquement que Nginx est cassé : elle dit souvent que ce qui est derrière lui répond mal, ou ne répond plus.

La chaîne réelle derrière un 502 bad gateway

Un site web moderne repose souvent sur plusieurs couches :

• un serveur de façade, Nginx, Apache ou un load balancer ;
• un service applicatif en amont, par exemple PHP-FPM, Node.js, Python WSGI ou ASGI ;
• parfois un proxy ou un CDN avant la façade ;
• éventuellement une base de données plus loin, mais ce n’est pas elle qui produit directement un 502.

Le point clé est simple : la réponse HTTP 502 est renvoyée par la passerelle qui n’a pas obtenu une réponse valide de son upstream. Si Nginx écoute sur le port 443, puis transmet vers un socket Unix PHP-FPM ou vers un port TCP applicatif, le journal d’erreur de Nginx indique en général l’élément précis en cause : socket introuvable, connexion refusée, en-tête invalide, délai dépassé.

Avant de modifier la configuration, commencez par identifier le rôle de chaque brique. Si le parcours du trafic n’est pas clair, comprendre les bases du réseau aide à distinguer ce qui relève du proxy, du DNS, du NAT et du service applicatif. Si un CDN est placé en amont, le rôle d’un CDN dans la chaîne de diffusion compte aussi, car un 502 peut être généré à plusieurs niveaux.

Commencer par le journal de la façade

Le premier réflexe d’administration n’est pas de redémarrer au hasard. Il faut lire le journal d’erreur du serveur qui a émis la réponse 502. C’est lui qui sait quel upstream a été contacté, sur quel socket ou quel port, et à quel moment l’échec s’est produit.

Dans une pile Nginx, les messages typiques contiennent souvent :

• connect() failed (111: Connection refused), le port ou le socket existe côté cible, mais aucun service n’accepte la connexion ;
• connect() to unix:… failed (2: No such file or directory), le socket attendu n’existe pas ;
• upstream timed out, le service répond trop lentement ;
• recv() failed ou upstream sent invalid header, la connexion s’établit mais la réponse reçue est invalide ou incomplète.

Le journal donne plus qu’un code : il nomme le coupable probable. C’est la différence entre une recherche méthodique et une suite de redémarrages. Si vous devez aussi diagnostiquer une erreur 500 dans les journaux du serveur, gardez en tête que le raisonnement n’est pas le même : ici, la façade accuse un service amont, elle ne plante pas forcément elle-même.

Quand le service en amont est arrêté

Le cas le plus net est aussi le plus rapide à confirmer. La façade tente de joindre un socket ou un port, mais personne ne répond. Vous voyez alors une erreur 502 nginx côté client, et dans les journaux un refus de connexion ou un socket introuvable.

Vérifiez dans cet ordre :

• si le service applicatif tourne réellement ;
• s’il écoute bien sur le port TCP attendu ou crée le socket Unix attendu ;
• si la configuration du proxy pointe vers la bonne cible ;
• si un déploiement récent a changé le chemin du socket, le port ou l’utilisateur du service.

Sur PHP-FPM, l’erreur classique est un décalage entre le socket déclaré côté Nginx et celui réellement créé par PHP-FPM. Sur Node.js ou Python, c’est souvent un processus tombé, un superviseur mal configuré ou un changement de port après déploiement. Inutile d’ajuster les timeouts si le service n’existe pas au point d’écoute attendu.

Quand l’upstream est saturé

Une erreur 502 apparaît aussi quand le service amont n’arrive plus à absorber la charge. Le processus existe, mais il ne traite plus correctement les connexions : workers bloqués, mémoire épuisée, file d’attente pleine, redémarrages en boucle. La façade reçoit alors une réponse incomplète, invalide, ou plus de réponse du tout avant coupure.

Les vérifications utiles sont concrètes :

• charge CPU et saturation des cœurs ;
• pression mémoire et éventuel déclenchement de l’OOM killer ;
• nombre de workers ou de processus disponibles ;
• temps moyen de traitement des requêtes ;
• pics simultanés après campagne, crawl intensif ou tâche planifiée.

Si l’origine est la montée en charge, le 502 n’est qu’un symptôme. Il faut ensuite corriger la capacité, la concurrence ou le code. Dans certains cas, optimiser le serveur web sans changer d’hébergement suffit à réduire les pointes qui font tomber l’upstream.

Quand le service répond trop lentement

Troisième grande famille, le service fonctionne, mais trop lentement pour la passerelle. La façade ouvre la connexion, attend, puis finit par journaliser un dépassement de délai. C’est un cas fréquent derrière des appels API lents, des requêtes SQL longues, un backend qui fait beaucoup d’I/O ou un réseau interne dégradé.

Il faut alors distinguer deux choses :

• la lenteur applicative réelle ;
• un timeout de proxy réglé plus bas que le temps de réponse normal, ce qui est plus rare mais possible.

Ne commencez pas par augmenter les délais. Mesurez d’abord la durée des requêtes lentes dans les journaux applicatifs et comparez-la au moment exact où la façade produit le 502. Si le chemin entre proxy et upstream passe par un autre hôte, une coupure ou une latence anormale peut aussi être en cause. Dans ce cas, une méthode de diagnostic d’une panne réseau évite de confondre lenteur applicative et incident de transport.

Comment savoir quelle passerelle a lâché

Sur des architectures avec plusieurs intermédiaires, reverse proxy local, load balancer, CDN ou proxy d’entrée, la question n’est pas seulement « quel service en amont a échoué ? », mais aussi « quelle passerelle renvoie le 502 ? ».

Pour le déterminer, suivez cette méthode :

• repérez quel composant termine TLS et renvoie la réponse au client ;
• comparez l’heure exacte du 502 avec les journaux de chaque couche ;
• relevez les en-têtes ajoutés par les proxys, quand ils sont configurés ;
• vérifiez si le message d’erreur ou la page générée correspond au style du CDN, du load balancer ou de Nginx.

Si seul le CDN journalise l’incident, la passerelle en faute peut être en amont de votre serveur de façade. Si le CDN est sain mais que Nginx logue un timeout vers PHP-FPM ou vers une application sur port TCP, le point de rupture est déjà trouvé. La bonne pratique consiste à corréler les horodatages plutôt qu’à déduire à l’aveugle.

Une méthode courte pour isoler la cause

Voici une séquence simple, adaptée à un administrateur avec accès SSH :

• identifier le composant qui a émis le 502 ;
• ouvrir son journal d’erreur et relever le message exact ;
• noter l’upstream mentionné, socket Unix ou port TCP ;
• vérifier si le service cible est démarré et à l’écoute ;
• contrôler la charge, la mémoire et les workers ;
• mesurer si la réponse dépasse les délais de la façade ;
• corréler avec un déploiement, un pic de trafic ou un incident réseau.

Cette méthode couvre l’essentiel des cas sans partir sur des hypothèses trop larges. Un bad gateway n’est pas un mystère abstrait : c’est une conversation ratée entre deux maillons, et le journal du maillon qui se plaint vous dit généralement lequel.

La réserve

Le 502 a une limite frustrante : il désigne bien une panne de passerelle, mais ne suffit pas à lui seul à prouver la cause racine. Un timeout vu par Nginx peut venir d’un code lent, d’une base en retard, d’un disque saturé, d’un réseau instable ou d’un worker bloqué. Autrement dit, le journal de façade localise très bien le maillon qui ne répond pas correctement, mais il ne remplace pas les journaux et les métriques du service amont. C’est une bonne boussole, pas un diagnostic complet à lui seul.

Questions frequentes

Que signifie le code 502 ?

Le code 502 signifie qu’une passerelle, souvent un reverse proxy ou un load balancer, a reçu une réponse invalide ou aucune réponse valable d’un service en amont. En pratique, le serveur de façade arrive à traiter la requête du client, mais pas à obtenir une réponse correcte du backend auquel il la transmet.

Comment puis-je contourner l'erreur 502 ?

Côté administration, on ne contourne pas durablement une erreur 502 sans identifier le maillon fautif. Il faut lire le journal de la passerelle, repérer l’upstream visé, puis vérifier si le service est arrêté, saturé ou trop lent. Un redémarrage peut rétablir le service, mais sans corriger la cause si elle revient sous charge.

Que signifie l'erreur 502 dans l'API ?

Dans une API, l’erreur 502 signifie qu’une passerelle, un proxy API ou un load balancer n’a pas obtenu de réponse valide du service backend. Le problème n’est pas forcément dans la requête du client : il peut venir d’un microservice indisponible, d’un timeout, d’une saturation ou d’une réponse mal formée en amont.