502 Bad Gateway Expliqué : Ce que cela signifie, pourquoi cela se produit et comment le dépanner

Mots-clés

Ce glossaire rapide couvre les mots d’infrastructure les plus susceptibles de créer de la confusion lors de la phase d’explication plus approfondie.

Pourquoi une erreur 502 semble si perturbatrice

Vous poussez un déploiement, rechargez le site, et le domaine répond instantanément — sauf que pas avec votre application. Ou un client clique sur Checkout, la page se charge, et la transaction échoue derrière un message stark 502 Bad Gateway. C’est ce qui rend cette erreur si stressante : le site est accessible, mais pas assez sain pour compléter le transfert.

Un 502 se situe dans un état intermédiaire maladroit. Ce n’est pas une disparition totale, mais ce n’est pas non plus un service qui fonctionne. Pour les développeurs, cela peut signifier un déploiement cassé ou une chaîne API défaillante. Pour les propriétaires d’entreprise, une perte de confiance ou des revenus interrompus. Pour les équipes, le pire est souvent la responsabilité : quel niveau possède réellement le problème ?

La façon utile de l’aborder est de ne pas deviner. D’abord, définissez ce que l’erreur signifie. Ensuite, cartographiez où elle se situe dans la chaîne de requêtes. Ensuite, dépannez l’échec logiquement, un transfert à la fois. Une fois que vous pouvez voir la chaîne, l’erreur cesse de sembler aléatoire.

Ce que signifie réellement une erreur 502 Bad Gateway

Une erreur 502 Bad Gateway signifie généralement qu’un serveur agissant comme passerelle ou proxy n’a pas pu utiliser la réponse qu’il a reçue de la couche suivante. En langage simple : un serveur a essayé de transmettre votre demande à un autre serveur, et ce transfert a échoué suffisamment gravement pour que le serveur frontal ne puisse pas retourner un résultat normal.

📝 Remarque : Si le serveur amont retourne une erreur HTTP valide de son côté, le proxy transmettra généralement cette erreur. Si l’application retourne un vrai 503 Service Unavailable, la couche frontale devrait normalement relayer ce 503, et non inventer un 502. Un 502 signifie que la réponse elle-même était inutilisable. Si aucune réponse utilisable n’arrive à temps, c’est souvent un 504 à la place.

Le moyen le plus rapide d’arrêter de mal interpréter les erreurs 5xx est de les séparer selon le lieu de la défaillance et la question qu’elles posent en premier :

⚠️ Avertissement : Ne regroupez pas 500, 502, 503 et 504 dans un seul panier générique « serveur arrêté ». Elles pointent vers différentes formes de défaillance, et cela change ce que vous devriez vérifier en premier.

Une fois que cette définition est claire, la question suivante devient beaucoup plus utile : où dans une pile réelle ce transfert échoué se produit-il réellement ?

Où l’erreur se produit dans une chaîne de requête réelle

La plupart des requêtes modernes ne voyagent pas directement du navigateur à l’application. Elles traversent des couches : navigateur vers CDN ou edge, edge vers reverse proxy ou load balancer, proxy vers le processus d’application. Un 502 devient visible à l’un de ces points de transfert.

Chaîne de requête simplifiée : Navigateur → CDN/Edge → Reverse Proxy / Load Balancer → App / Process

Un reverse proxy accepte la requête publique et la transfère en interne. Un load balancer fait quelque chose de similaire, mais peut choisir entre plusieurs cibles saines. Dans les deux cas, la couche avant effectue le routage de la requête, pas la logique métier elle-même.

L’analogie de la réception fonctionne bien ici. Pensez au proxy comme à la réception d’un immeuble de bureaux. Il enregistre le visiteur, cherche le bon bureau et essaie de le transférer. Si le bureau ne répond pas, répond sur la mauvaise ligne ou donne une réponse que la réception ne peut pas utiliser, la réception retourne l’échec. C’est pourquoi l’erreur visible apparaît souvent à la couche proxy même quand la cause profonde se situe ailleurs.

📝 Note : Le proxy est souvent le messager de l’échec, pas la cause originelle.

Le « serveur suivant » derrière cette réception peut être un service HTTP normal sur un port, un écouteur d’application tel que 127.0.0.1:3000, ou un processus soutenu par un socket local tel que PHP-FPM. Le problème racine n’a pas besoin de vivre dans le proxy. Un mauvais déploiement, un worker d’application écrasé ou même une défaillance de base de données peuvent casser le backend suffisamment pour que le proxy soit simplement l’endroit où le 502 apparaît.

Les services edge ajoutent une autre complication. Un CDN tel que Cloudflare peut transférer un 502 côté origine de plus profond dans votre pile, ou il peut générer un 502 lui-même quand le transfert edge-to-origin échoue. C’est pourquoi « qui a retourné cette erreur ? » est la première question pratique, pas une réflexion après coup.

Pourquoi les erreurs 502 se produisent : les principales catégories de défaillance

Une fois que vous cessez de traiter un 502 comme un événement mystérieux, le paysage des causes devient beaucoup plus facile à gérer. La plupart des incidents entrent dans trois catégories réutilisables : l’upstream est indisponible, le transfert lui-même est mal configuré, ou la réponse revient sous une forme que la passerelle ne peut pas utiliser.

Le premier bucket est le plus évident : l’upstream n’est pas disponible dans un état utilisable. Peut-être que l’application s’est arrêtée après le déploiement. Peut-être que le service n’a jamais redémarré. Peut-être qu’un pool PHP-FPM est mort, ou qu’une cible a été marquée comme défaillante et supprimée de la rotation. C’est le scénario classique « service arrêté », mais ce n’est qu’une partie du paysage des 502.

Le deuxième bucket est le décalage de transfert. Ici, les deux couches peuvent être en cours d’exécution, mais elles ne sont pas d’accord sur la façon de se joindre. Le proxy peut pointer vers le mauvais port. Un nom d’hôte peut se résoudre incorrectement. Un pare-feu peut bloquer le chemin. Une couche peut s’attendre à HTTPS tandis que la suivante ne parle que HTTP simple. Un chemin de socket peut avoir changé. Dans ces cas, l’application peut être saine et la connexion entre les couches est toujours cassée.

Le troisième bucket est plus délicat : l’upstream répond, mais pas d’une manière que la passerelle peut utiliser. Une cible peut réinitialiser la connexion TCP, la fermer trop tôt, envoyer des en-têtes malformés ou surdimensionnés, ou retourner une sortie partielle sous charge. L’application n’est pas simplement « arrêtée » ; elle répond assez mal pour que la passerelle rejette ce qu’elle a reçu.

C’est aussi pourquoi 502 n’est pas juste une histoire de délai d’expiration. Certains cas de délai d’expiration deviennent 504 Gateway Timeout, pas 502. Cloudflare peut afficher les 502 générés par les bords lorsque la connectivité d’origine ou la compression se casse. Les équilibreurs de charge peuvent émettre des 502 lors de problèmes de synchronisation de désenregistrement ou d’échecs de poignée de main TLS. « Service arrêté » est une catégorie de cause, pas la définition de l’erreur.

Ce modèle mental vous donne une véritable liste de contrôle avant même de toucher à un fichier de configuration. Demandez-vous dans quel bucket vous êtes probablement, puis testez pour trouver des preuves. C’est ce qui rend la séquence de dépannage logique au lieu de rituelle.

Une séquence de dépannage intelligente pour les erreurs 502

Le moyen le plus rapide de dépanner une erreur 502 est d’identifier quelle couche l’a renvoyée, puis de tester le prochain saut derrière cette couche avant de modifier quoi que ce soit. L’objectif est de prouver où se trouve l’échec du transfert.

💡 Conseil : Avant de redémarrer ou de modifier quoi que ce soit, identifiez qui a renvoyé l’erreur 502. Une étape d’attribution claire économise souvent plus de temps que les cinq premiers « correctifs » que les gens essaient sous pression.

Phase 1 : Identifier la couche

Commencez par le côté public et demandez-vous ce que la couche exposée à Internet retourne réellement :

curl -I https://example.com

Cela affiche le statut HTTP et les en-têtes de l’URL publique. Si les en-têtes appartiennent clairement à un CDN, un équilibreur de charge ou un proxy inverse, vous avez votre premier indice. Si la page d’erreur porte la marque de Cloudflare, Cloudflare a peut-être généré l’erreur 502 elle-même ; si elle n’est pas marquée, l’edge peut simplement transmettre un échec côté origine. Des en-têtes tels que cf-error-type ou cf-error-origin peuvent apparaître sur les pages d’erreur générées par Cloudflare, ce qui est utile précisément parce qu’ils n’apparaissent pas sur chaque 502.

📝 Remarque : Si un seul visiteur voit l’erreur tandis que d’autres peuvent accéder au site, les paramètres VPN locaux, proxy, pare-feu ou DNS peuvent toujours faire partie du problème. Une erreur 502 est généralement côté serveur, mais un chemin client isolé peut obscurcir ce que vous observez.

Phase 2 : Vérifier le chemin en amont

Une fois que vous savez quelle couche a renvoyé l’erreur 502, testez le prochain saut derrière elle. Si un proxy inverse est impliqué, confirmez que le proxy et le service backend s’exécutent tous les deux, et confirmez que l’écouteur attendu existe :

systemctl status nginx
systemctl status <app-service>
ss -tlnp

Remplacez <app-service> par le nom de votre service backend. systemctl status vous indique si le processus proxy ou application est actif, défaillant ou en redémarrage. ss -tlnp montre si quelque chose écoute réellement sur le port que vous attendez.

Testez ensuite si le backend répond directement sans le proxy au milieu :

curl -i http://127.0.0.1:3000

Si la demande directe fonctionne mais l’URL publique retourne toujours 502, le backend peut être sain et le transfert peut être le vrai problème. Cela vous oriente vers les paramètres de cible proxy, les incompatibilités de protocole, les noms d’hôte en amont, les attentes TLS ou les règles de pare-feu plutôt que vers le code d’application seul.

Phase 3 : Utiliser les commandes comme preuve, pas comme cérémonie

Après les vérifications directes, passez aux preuves qui expliquent pourquoi le transfert échoue :

journalctl -u nginx -u <app-service> --since "15 min ago"
dig +short example.com
nginx -t

Ces trois vérifications répondent à des questions différentes. journalctl met en évidence les plantages récents, les réinitialisations, les indices de délai d’attente et les défaillances liées au déploiement. dig +short vous indique si le nom d’hôte dont vous dépendez se résout de la manière que le serveur attend. nginx -t valide la syntaxe du proxy inverse avant de recharger quoi que ce soit, ce qui importe car une mauvaise définition en amont peut générer une erreur 502 même quand le backend va bien.

Les signaux pratiques ressemblent généralement à ceci :

C’est le motif principal à retenir : identifiez la couche, vérifiez le prochain saut, puis utilisez les logs et les tests directs pour expliquer l’inadéquation. Les preuves d’abord. Les paramètres ensuite.

Comment le chemin de dépannage change selon le modèle d’hébergement

Le prochain pas après un 502 dépend de la quantité de pile que vous contrôlez. La logique de dépannage reste la même, mais la quantité que vous pouvez inspecter vous-même change beaucoup entre l’hébergement mutualisé, les VPS, les serveurs dédiés et les configurations avec proxy en périphérie.

📝 Remarque : Sur l’hébergement mutualisé, l’escalade n’est pas une échappatoire. C’est souvent le bon geste technique car les couches les plus importantes pour un 502 peuvent être en dehors de votre visibilité.

Sur l’hébergement mutualisé, la chose la plus utile que vous puissiez faire est de collecter des preuves : l’heure, l’URL affectée, si l’erreur est constante ou intermittente, et si elle a commencé après un déploiement ou un changement de configuration. Cela donne au support quelque chose d’exploitable. Si vous ne contrôlez pas le reverse proxy, le service d’application ou les journaux du serveur, le diagnostic significatif couche par couche s’arrête rapidement.

Sur un VPS, le flux de travail complet devient réaliste car vous pouvez inspecter les services, les écouteurs, les journaux et la configuration du proxy directement. C’est là que le dépannage du reverse-proxy a sa place. Sur l’infrastructure VPS d’AlexHost, vérifier systemctl, journalctl, ss, les cibles en amont et la configuration Nginx fait partie de la propriété normale, pas quelque chose toujours caché derrière le support.

Un serveur dédié vous donne la même visibilité, mais avec plus de responsabilité. Vous possédez plus de la pile complète, et possiblement plus des hypothèses réseau environnantes aussi. Si vous ajoutez un CDN ou un autre service en périphérie, la première question de propriété reste la même : la périphérie a-t-elle généré le 502, ou a-t-elle transmis une défaillance côté origine ? Plus de contrôle ne rend pas le dépannage plus simple par défaut. Cela vous donne plus d’endroits à inspecter.

Pensez par couches, pas en panique

Une erreur 502 Bad Gateway cesse de sembler mystérieuse une fois que vous la traitez pour ce qu’elle est généralement : un transfert échoué entre serveurs, pas un événement aléatoire du navigateur. Le navigateur est seulement l’endroit où vous le remarquez. L’histoire réelle se trouve dans la couche qui transmet la demande à la suivante et qui échoue à obtenir quelque chose d’utilisable.

Gardez donc la séquence simple : identifiez la couche, vérifiez le prochain saut, validez avec des tests directs et des journaux, et modifiez les paramètres uniquement lorsque les preuves pointent vers un endroit spécifique. Si les incidents récurrents vous poussent continuellement vers une meilleure visibilité des journaux, des proxies et des services, c’est le moment où les environnements à contrôle plus élevé — y compris les VPS AlexHost ou les serveurs dédiés — deviennent utiles pour des raisons opérationnelles, pas marketing. La méthode prime sur la mémorisation ici.