HTTP 502 Bad Gateway — Causes et corrections

Ce que signifie HTTP 502

HTTP 502 Bad Gateway provient d'un intermédiaire — nginx, un load balancer, Cloudflare — qui a transmis votre requête à un serveur backend et reçu une réponse invalide : une connexion refusée, un plantage en cours de réponse, ou des octets qui ne s'analysent pas comme du HTTP.

Le coupable désigné n'est presque jamais le proxy lui-même ; c'est le serveur d'application derrière lui qui est en panne, surchargé ou inaccessible.

Causes courantes des erreurs 502

Le serveur d'application (PHP-FPM, Node, gunicorn, etc.) a planté ou ne s'exécute pas.
Le proxy pointe vers le mauvais port/socket, ou un pare-feu bloque la connexion vers le backend.
La réponse du backend a dépassé les buffers ou a expiré en cours de transfert.
Un déploiement a redémarré les backends alors que du trafic circulait.
Avec des CDN comme Cloudflare : le serveur d'origine est en panne alors que l'edge fonctionne.

Comment la corriger en tant que visiteur

Rechargez après une minute — les 502 pendant les déploiements se résolvent d'eux-mêmes.
Consultez la page de statut du service si cela persiste.

Comment la corriger en tant que développeur

Vérifiez si le processus backend est vivant et à l'écoute sur l'adresse attendue par le proxy.
Lisez le log d'erreurs du proxy — nginx indique exactement pourquoi (connect() failed, upstream prematurely closed, etc.).
Vérifiez les ports, les chemins de socket unix et les règles de pare-feu entre le proxy et l'application.
Ajoutez des health checks pour que le load balancer arrête de router vers des instances mortes.

Exemple de réponse

HTTP/1.1 502 Bad Gateway
Server: nginx
Content-Type: text/html

<html><body><h1>502 Bad Gateway</h1></body></html>

FAQ

Quelle est la différence entre 502 et 504 ?

502 signifie que le backend a répondu par quelque chose d'invalide (ou a refusé la connexion) ; 504 signifie qu'il n'a pas du tout répondu dans le délai imparti.

Pourquoi Cloudflare affiche-t-il 502 ?

L'edge de Cloudflare n'a pas pu obtenir de réponse valide de votre serveur d'origine — l'origine est en panne, inaccessible ou renvoie des réponses malformées.

Un 502 est-il temporaire ?

Généralement oui — déploiements et redémarrages provoquent de brefs 502. Des 502 persistants signifient que le backend est réellement en panne ou mal configuré.