Erreur 502 Bad Gateway : causes et guide de dépannage

Une erreur 502 Bad Gateway signifie qu un serveur a reçu une réponse invalide d un autre serveur en amont. La plupart du temps c est passager : actualisez la page, videz le cache, essayez un autre réseau ou attendez quelques minutes. Si vous êtes propriétaire du site, vérifiez les logs, la configuration du proxy/CDN et la santé des services en amont.

Qu est‑ce qu une erreur 502 Bad Gateway

Une erreur 502 Bad Gateway indique un problème de communication entre serveurs. Concrètement, le serveur auquel votre navigateur s est connecté n a pas obtenu une réponse valide d un autre serveur dont il dépend. Cela ne veut pas dire que le site est définitivement cassé. Souvent, c est un accroc temporaire : un service en cours de redémarrage, un proxy surchargé, ou un timeout.

Définition en une ligne

• 502 Bad Gateway : erreur HTTP indiquant qu un serveur intermédiaire a reçu une réponse invalide d un serveur en amont.

Principaux acteurs impliqués

• Client : navigateur ou application qui effectue la requête.
• Serveur frontal : serveur qui répond au client (reverse proxy, load balancer, CDN).
• Serveur en amont : application ou service final qui traite la requête.

Causes fréquentes

• Service en amont indisponible ou en redémarrage.
• Timeout entre le proxy et le serveur d application.
• Mauvaise configuration du reverse proxy (Nginx, HAProxy, Cloudflare).
• Règles de pare‑feu ou filtrage réseau bloquant les connexions.
• Problèmes DNS ou cache DNS obsolète.
• Réponse invalide envoyée par un module tiers (API externe, plugin).
• Surcharge du serveur provoquant des erreurs 502 intermitentes.

Étapes rapides pour les utilisateurs finaux

Ces actions s appliquent si vous rencontrez l erreur sur un site public et que vous n en êtes pas le propriétaire.

1. Actualiser la page

Souvent, le problème est transitoire. Appuyez sur F5 ou cliquez sur le bouton d actualisation du navigateur.

2. Essayer un autre navigateur, appareil ou réseau

Changez de navigateur ou utilisez votre smartphone en 4G pour tester si le problème vient de votre réseau local ou d une politique organisationnelle.

3. Vider le cache du navigateur

Un cache corrompu peut renvoyer des requêtes erronées. Procédez ainsi :

• Ouvrir l historique du navigateur.
• Cliquer sur effacer les données de navigation.
• Sélectionner images et fichiers en cache.
• Confirmer et recharger le site.

4. Vider le cache DNS local

Sur Windows, ouvrir l invite de commandes et taper :

ipconfig /flushdns

Puis redémarrer le navigateur.

5. Attendre 5 à 10 minutes

Si le problème vient du serveur en amont, les équipes techniques le voient souvent et le corrigent. Attendre quelques minutes peut suffire.

Vérifications pour le propriétaire du site ou l administrateur

Si vous gérez le site, vous avez accès aux logs et à l infrastructure. Suivez ce processus structuré.

1. Vérifier les logs

• Logs du reverse proxy (Nginx, HAProxy, Cloudflare). Rechercher 502, upstream failed, upstream timed out.
• Logs d application (PHP, Node.js, Gunicorn). Rechercher exceptions, erreurs de démarrage.
• Logs système (dmesg, syslog) pour détecter OOM killer ou problèmes réseau.

Exemple Nginx error_log pertinent :

2025/08/17 12:34:56 [error] 12345#0: *6789 upstream prematurely closed connection while reading response header from upstream, client: 10.0.0.1, server: example.com, request: "GET /api/data HTTP/1.1", upstream: "http://127.0.0.1:8000/", host: "example.com"

2. Contrôler la santé des services en amont

• Confirmer que les processus d application tournent.
• Tester directement l endpoint en amont via curl ou wget.
• Surveiller l utilisation CPU, mémoire, des descripteurs de fichiers.

Exemple de test rapide :

curl -I http://127.0.0.1:8000/endpoint

3. Vérifier la configuration du proxy et les timeouts

• Timeouts trop courts provoquent des 502 si l application met plus de temps à répondre.
• Paramètres à contrôler pour Nginx : proxy_read_timeout, proxy_connect_timeout, proxy_send_timeout.
• Pour HAProxy : timeout connect, timeout server, timeout client.

4. Examiner la configuration CDN

Si vous utilisez un CDN ou un WAF, vérifiez :

• Que les règles de sécurité ne bloquent pas les IPs en amont.
• Les paramètres d origine (origin) et l adresse IP du serveur final.
• Les réglages de mise en cache et d en‑têtes.

5. Tester l environnement réseau

• Ping et traceroute vers l hôte d origine.
• Vérifier les règles de pare‑feu et ACLs.
• Confirmer que le reverse proxy résout correctement le nom DNS de l origine.

Playbook d intervention rapide pour incidents 502

1. Identifier l étendue : pages affectées, pourcentage de trafic.
2. Reproduire : curl depuis le proxy et depuis un hôte externe.
3. Analyser logs proxy puis logs applicatifs.
4. Redémarrer le processus incriminé si nécessaire.
5. Si redémarrage insuffisant : basculer vers un backup origin ou une maintenance page.
6. Postmortem : collecter traces, corriger la cause racine.

Important

• Toujours coordonner les redémarrages en heures creuses si possible.
• Conserver des backups de configuration avant toute modification.

Runbook de rollback et mitigation

Mitigation immédiate

• Activer une page de maintenance statique pour diminuer la charge.
• Basculez le trafic vers une instance saine si vous avez un load balancer.

Rollback

• Restaurer la configuration du reverse proxy si un changement récent a provoqué l erreur.
• Revenir au dernier déploiement stable si une mise à jour applicative est en cause.

Cas particuliers et contre‑exemples

Quand une actualisation ne suffit pas

• Erreurs 502 persistantes sur toutes les pages indiquent un problème côté serveur.
• Erreurs 502 intermittentes seulement sur certaines ressources peuvent indiquer une API tierce défaillante.

Quand ce n est pas un 502

• Erreur 504 signifie timeout côté upstream plutôt qu une réponse invalide.
• Erreur 503 signifie service indisponible ou en maintenance.

Tests d acceptation (exemples)

• Test 1 : curl renvoie 200 pour l endpoint en amont sous charge normale.
• Test 2 : reverse proxy renvoie 502 lorsque l application est arrêtée.
• Test 3 : après ajustement des timeouts, l endpoint lent renvoie 200 dans un délai raisonnable.

Maturité et heuristique de priorisation

• Niveau 1 (monitoring) : alertes sur taux de 502 > seuil en 5 minutes.
• Niveau 2 (automation) : bascule automatique vers origin de secours.
• Niveau 3 (résilience) : mise en cache côté CDN et limitation des dépendances synchrones.

Matrice de décisions rapide

• Si le problème est généralisé et soudain : vérifier la couche réseau et CDN.
• Si le problème est récent après déploiement : considérer rollback.
• Si l erreur survient uniquement pour certains utilisateurs : regarder géolocalisation et DNS.

Sécurité et confidentialité

• Les erreurs 502 peuvent exposer des traces d application dans les logs. Nettoyez ou anonymisez les données sensibles avant de partager des logs.
• Respectez la réglementation sur les données personnelles lors des partages externes.

Glossaire rapide

• Reverse proxy : serveur qui reçoit des requêtes client et les redirige vers un ou plusieurs serveurs d application.
• Upstream : serveur en amont qui traite la requête finale.
• CDN : réseau de distribution de contenu, interpose souvent un cache entre le client et l origine.

Diagramme de décision

flowchart TD
  A[Utilisateur voit 502] --> B{Le site est-il accessible pour d autres?}
  B -- oui --> C[Tester réseau local: vider cache, DNS, essayer 4G]
  B -- non --> D{Vous êtes propriétaire du site?}
  D -- non --> E[Patienter et contacter support du site]
  D -- oui --> F[Consulter logs proxy puis logs applicatifs]
  F --> G{Erreur due à l application?}
  G -- oui --> H[Redémarrer service ou rollback]
  G -- non --> I[Vérifier CDN / pare-feu / timeouts]
  H --> J[Surveiller et documenter]
  I --> J

Pratiques recommandées pour éviter les 502

• Configurer des timeouts raisonnables côté proxy.
• Mettre en place des health checks et un origin de secours.
• Surveiller les ressources et la latence des services en amont.
• Découpler les dépendances critiques et utiliser des files d attente pour les opérations longues.

Conclusion

Une erreur 502 Bad Gateway est souvent un symptôme de communication défaillante entre serveurs. Pour les utilisateurs, les mesures simples comme actualiser la page, vider le cache ou changer de réseau résolvent souvent le problème. Pour les propriétaires de site, l intervention passe par l analyse des logs, la vérification de la santé des services en amont, l ajustement des timeouts et la configuration du CDN ou du reverse proxy. Avec une bonne surveillance et des plans de mitigation, les incidents 502 restent gérables et rarement catastrophiques.

Résumé

• 502 signifie réponse invalide d un serveur en amont.
• Pour un utilisateur : actualiser, vider le cache, changer de réseau, attendre.
• Pour un administrateur : lire les logs, tester l origine, ajuster timeouts, vérifier CDN.

Si vous avez des remarques ou un cas concret sur l erreur 502 Bad Gateway, laissez un commentaire. Abonnez‑vous à la chaîne DigitBin pour des tutoriels vidéo si vous souhaitez une démonstration pas à pas.