Erreur 502 Bad Gateway : que faire côté visiteur et côté serveur ?

Erreur 502 Bad Gateway : elle signale qu’un serveur passerelle ou un proxy a reçu une réponse invalide de l’amont. En clair, le problème vient généralement du côté serveur, mais certains réglages côté visiteur peuvent aussi provoquer l’affichage de cette page. Voici quoi faire, selon votre situation.

Comprendre l’erreur 502 en une phrase

Le code HTTP 502 indique que le serveur qui relaie votre requête. CDN, reverse proxy, pare-feu applicatif, load balancer, a bien contacté l’upstream mais a reçu une réponse non conforme ou corrompue, et vous renvoie donc « Bad Gateway ».

Avant d’agir : 502 n’est pas 500, 503 ou 504

La nuance oriente le diagnostic. 500 est une erreur interne générique sur un serveur donné. 503 signifie service indisponible, souvent pour surcharge ou maintenance, et peut être temporaire avec un en-tête Retry-After. 504 est un délai dépassé : la passerelle n’a reçu aucune réponse dans les temps. 502 cible un point précis de la chaîne où une réponse mal formée ou invalide a été renvoyée.

Que faire côté visiteur : 6 vérifications utiles

La majorité des 502 se résolvent côté site. Toutefois, des paramètres locaux peuvent tromper le proxy et produire une réponse invalide. Procédez ainsi, dans l’ordre, en testant après chaque étape :

• Actualiser et tester une page neutre du site. Un simple rafraîchissement ou la visite d’une autre URL du même domaine permet d’écarter un incident ponctuel de cache.
• Désactiver VPN, proxy utilisateur et bloqueurs. Un VPN qui réécrit le trafic, un proxy local, une extension anti-traqueurs ou de filtrage HTTPS peuvent altérer la requête. Refaire le test en navigation privée et sans extension.
• Changer de réseau. Passer du Wi-Fi à la 4G/5G ou inversement pour vérifier si l’erreur vient d’un résolveur DNS, d’un pare-feu d’entreprise ou d’un CGNAT.
• Vider le cache DNS local. Sous Windows, exécuter « ipconfig /flushdns » dans l’invite de commandes. Sous macOS, « sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder ». Redémarrer le navigateur.
• Tester un autre résolveur DNS. Configurer temporairement un DNS public fiable. Si le site se résout alors vers une autre IP et fonctionne, le problème tient à une résolution incohérente.
• Signaler l’incident. Si d’autres utilisateurs accèdent au site quand vous non, envoyez l’horodatage précis, l’URL, votre IP publique et une capture d’écran au support. Plus ces éléments sont précis, plus le diagnostic côté serveur gagne du temps.

Que faire côté serveur : méthode de diagnostic rapide

Objectif : identifier où la chaîne « client → passerelle → upstream » se brise et pourquoi la réponse d’amont est invalide. Travaillez en environnement de préproduction si possible et collectez un timeline minimal : heure, cluster/POP, IP client, ID de requête, corrélations de logs.

1. Confirmer le périmètre et reproduire

Vérifiez si l’erreur 502 touche un route spécifique, un microservice, un datacenter, ou tout le site. Utilisez un même User-Agent et les mêmes en-têtes que le client impacté. Un curl verbeux est idéal : curl -vI https://domaine.tld/route. Relevez le point qui répond 502 : CDN, WAF, reverse proxy, load balancer, ou passerelle API.

2. Inspecter les logs de la passerelle

Recherchez les signatures classiques de 502 : upstream sent no valid HTTP/1.1 header, invalid chunk size, upstream prematurely closed connection, bad status line, TLS handshake failed, header too large. Ces messages indiquent soit un protocole mal négocié, soit une troncature de réponse.

3. Tester l’upstream en direct

Interrogez le service d’amont sans passerelle pour voir si la réponse est conforme HTTP. Exemple : curl -v -resolve api.domaine.tld:443:IP_UPSTREAM https://api.domaine.tld/health. Si la réponse est correcte en direct mais 502 via la passerelle, ciblez la configuration proxy. Si elle est déjà invalide, la panne est applicative ou réseau entre l’amont et le proxy.

Causes fréquentes côté serveur et correctifs

Négociation protocolaire incohérente. Un proxy en HTTP/1.1 vers une application qui parle HTTP/2 clair, gRPC, WebSocket non surclassé, ou un h2c mal déclaré, provoque une ligne de statut illisible. Alignez la version HTTP/ALPN, forcez HTTP/1.1 si nécessaire, ou activez le support gRPC côté passerelle.

Timeouts mal dimensionnés. Un 504 traduit l’absence de réponse, mais un 502 peut survenir si l’amont coupe brutalement. Harmonisez read_timeout, send_timeout et keepalive entre proxy et upstream, et ajoutez des health checks pour sortir rapidement un nœud moribond du pool.

Réponses tronquées ou mal formées. En-têtes dépassant la limite, Transfer-Encoding incohérent, Content-Length erroné, encodage chunked interrompu : augmentez prudemment les tailles de buffers côté proxy et corrigez le middleware qui écrit la réponse. Des tests d’intégration doivent valider les en-têtes et la complétude du corps.

Problèmes TLS vers l’amont. Certificat expiré, chaîne incomplète, SNI manquant, version ou suite cryptographique refusée entraînent des échecs de négociation et donc une réponse invalide. Mettez à jour le certificat, renseignez le server_name côté proxy et synchronisez les politiques TLS.

Résolution DNS instable de l’upstream. Une IP d’amont qui « flap » ou un TTL trop long peut envoyer la passerelle vers une cible fermée. Activez la résolution DNS dynamique dans le proxy, réduisez le TTL et surveillez les échecs de connexion par IP.

Équilibrage et réseau. Paquets fragmentés, MTU inadaptée entre segments, règles de pare-feu ou de sécurité L7 qui injectent une page HTML au milieu d’une réponse JSON génèrent une réponse illisible par la passerelle. Standardisez la MTU, désactivez la réécriture de contenu non HTML et revoyez les règles d’inspection.

Crashes applicatifs et redémarrages. Un processus qui segfault ou se fait tuer par l’OOM killer coupe la socket avant d’émettre une réponse HTTP valide. Surveillez la mémoire, limitez la taille des workers, mettez en place des graceful shutdowns et des redémarrages contrôlés.

Compression et encodage. Double compression gzip, contenu binaire compressé à la volée puis filtré par un module mal configuré : validez Content-Encoding et évitez les doubles traitements sur le même flux.

Plan d’action recommandé pour les équipes techniques

1. Isoler le point fautif avec un traçage distribué minimal : ID de requête propagé, journaux corrélés proxy ↔ amont.
2. Répliquer avec des tests curl/h2c et activer temporairement une page de maintenance edge pour protéger l’expérience.
3. Corriger le paramètre identifié : protocole/ALPN, timeouts, buffers, SNI, DNS dynamique, règles WAF, taille d’en-têtes.
4. Valider en préprod avec tests d’intégration réseau et contract tests des en-têtes.
5. Durcir la prévention : health checks, circuit breakers, quotas raisonnables, budgets de temps par dépendance, et alertes sur signatures de 502.

Exemples de réglages utiles selon l’infrastructure

Nginx en reverse proxy. Vérifier proxy_http_version 1.1 si l’amont exige des connexions persistantes, définir proxy_set_header Connection «  » pour éviter « Connection: close » indésirable, ajuster proxy_read_timeout et proxy_busy_buffers_size. Activer proxy_ssl_server_name on si l’amont se sélectionne par SNI.

HAProxy / Load balancer. Uniformiser option http-keep-alive, vérifier http-reuse, régler tune.bufsize si les en-têtes sont volumineux, et valider server avec check-ssl verify required sni str(api.domaine.tld).

CDN ou WAF. Désactiver temporairement les règles qui réécrivent le corps de réponse JSON/GraphQL, et vérifier les modes « Orange to Orange » ou « Proxy to Proxy » qui créent une double passerelle sensible aux divergences de protocole.

Quand escalader et quoi communiquer aux utilisateurs

Si l’analyse dépasse 30 minutes sans hypothèse robuste, escaladez vers l’équipe réseau/plateforme avec captures pcap sur la liaison proxy ↔ amont, horodatées. Côté communication, affichez une page d’état mentionnant l’heure de début, la portée, la cause identifiée et un délai de résolution estimé. Un 502 bien expliqué vaut mieux qu’un silence : vous réduisez les tickets et protégez votre réputation.

En pratique, côté visiteur, limitez vos essais à quelques vérifications locales puis signalez l’heure exacte et l’URL au support. Côté serveur, attaquez d’abord la cohérence protocolaire et les timeouts, puis la santé de l’upstream. Ce fil de diagnostic résout l’essentiel des erreurs 502 Bad Gateway rapidement et durablement.