HTTPTools

HTTP 502 Bad Gateway

Die Beschwerde des Vermittlers: Ein Proxy oder CDN hat den echten Server gefragt und Unsinn — oder gar nichts — zurückbekommen.

Was HTTP 502 bedeutet

HTTP 502 Bad Gateway stammt von einem Vermittler — nginx, einem Load Balancer, Cloudflare —, der deinen Request an einen Upstream-Server weitergeleitet und eine ungültige Antwort erhalten hat: eine abgelehnte Verbindung, ein Absturz mitten in der Antwort, oder Bytes, die sich nicht als HTTP parsen lassen.

Der eigentliche Schuldige ist so gut wie nie der Proxy selbst; es ist der dahinterliegende Anwendungsserver, der down, überlastet oder nicht erreichbar ist.

Häufige Ursachen von 502-Fehlern

  • Der Anwendungsserver (PHP-FPM, Node, gunicorn usw.) ist abgestürzt oder läuft nicht.
  • Der Proxy zeigt auf den falschen Port/Socket, oder eine Firewall blockiert die Upstream-Verbindung.
  • Die Upstream-Antwort hat Puffer überschritten oder ist mitten in der Übertragung in ein Timeout gelaufen.
  • Ein Deployment hat Backends neu gestartet, während Traffic floss.
  • Bei CDNs wie Cloudflare: Der Origin-Server ist down, während der Edge in Ordnung ist.

So behebst du es als Besucher

  • Lade nach einer Minute neu — 502er während Deployments lösen sich von selbst.
  • Prüfe die Statusseite des Dienstes, falls es weiterhin auftritt.

So behebst du es als Entwickler

  • Prüfe, ob der Upstream-Prozess läuft und auf der vom Proxy erwarteten Adresse lauscht.
  • Lies das Fehlerprotokoll des Proxys — nginx sagt genau, warum (connect() failed, upstream prematurely closed usw.).
  • Prüfe Ports, Unix-Socket-Pfade und Firewall-Regeln zwischen Proxy und App.
  • Füge Health-Checks hinzu, damit der Load Balancer aufhört, an tote Instanzen weiterzuleiten.

Beispielantwort

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

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

FAQ

Was ist der Unterschied zwischen 502 und 504?

502 bedeutet, dass der Upstream mit etwas Ungültigem geantwortet hat (oder die Verbindung ablehnte); 504 bedeutet, dass er innerhalb des Timeouts überhaupt nicht geantwortet hat.

Warum zeigt Cloudflare 502 an?

Der Edge von Cloudflare konnte keine gültige Antwort von deinem Origin-Server bekommen — der Origin ist down, nicht erreichbar oder liefert fehlerhafte Antworten.

Ist eine 502 vorübergehend?

Meist ja — Deployments und Neustarts verursachen kurze 502er. Anhaltende 502er bedeuten, dass das Backend wirklich down oder fehlkonfiguriert ist.