504 Gateway Timeout: langsame Backends, Timeouts und 502 vs. 503 vs. 504
Ein 504 Gateway Timeout bedeutet, dass ein Proxy Ihr Backend erreicht, auf eine Antwort gewartet und aufgegeben hat, bevor eine eintraf. Nichts ist abgestürzt und nichts hat die Anfrage abgelehnt: Etwas hinter dem Proxy ist langsamer, als der Proxy zu warten bereit ist.
Was ein 504 meldet
RFC 9110 definiert 504 für einen Server, der als Gateway oder Proxy fungiert und keine rechtzeitige Antwort von einem Upstream-Server erhalten hat, den er kontaktieren musste. Das Wort "rechtzeitig" wird durch Konfiguration festgelegt, nicht durch die Spezifikation, ein 504 ist also immer eine Aussage über zwei Dinge gleichzeitig: wie langsam das Backend war, und auf welches Limit der Proxy eingestellt war.
Das hat eine wichtige praktische Konsequenz. Wenn ein Proxy 504 zurückgibt, arbeitet das Backend meist weiter an der Anfrage. Die Verbindung zum Client ist weg, aber die langsame Abfrage läuft noch, der Bericht wird noch erzeugt, und die Ressourcen bleiben belegt. Deshalb macht eine Welle von 504ern einen Server oft noch schlimmer: Jede verlassene Anfrage hinterlässt Arbeit, und die Warteschlange wächst schneller, als sie sich leert.
504 gegenüber 502 gegenüber 503
| 502 Bad Gateway | 503 Service Unavailable | 504 Gateway Timeout | |
|---|---|---|---|
| Was passiert ist | Backend gab eine ungültige Antwort oder schloss die Verbindung | Server hat die Arbeit absichtlich abgelehnt | Backend hat die Arbeit angenommen und nie rechtzeitig geantwortet |
| Backend-Zustand | Nicht erreichbar, abstürzend, oder spricht das falsche Protokoll | Erreichbar, aber überlastet oder in Wartung | Erreichbar und beschäftigt, verarbeitet noch |
| Antwortgeschwindigkeit | Meist sofort | Meist sofort | Langsam, kommt am Timeout-Limit an |
| Typische Protokollzeile | connect() failed oder upstream prematurely closed connection | Wartungsregel, oder keine gesunden Upstreams | upstream timed out (110: Connection timed out) |
Retry-After | Nicht üblich | Üblich und empfohlen | Nicht üblich |
| Erster Ansatzpunkt | Läuft der Backend-Prozess? | Kapazität, Wartungsflags, Health-Checks | Langsame Abfragen und langsame Abhängigkeiten |
In der Praxis schlägt ein 502 schnell fehl, ein 503 lehnt höflich ab, und ein 504 lässt Sie erst warten. Die eigene 502-Anleitung und die 5xx-Übersicht behandeln die anderen beiden vollständig.
Warum das Backend zu langsam ist
- Langsame Datenbankabfragen. Ein fehlender Index, eine Abfrage, die mit den Daten mitgewachsen ist, ein N+1-Muster in einer Schleife, oder Lock-Konkurrenz unter Parallelität. Die mit Abstand häufigste Ursache.
- Langsame Drittanbieter-Aufrufe. Eine ausgehende API-Anfrage ohne eigenes Timeout erbt den schlechtesten Tag des entfernten Dienstes und gibt ihn an Ihre Besucher weiter.
- Cold Starts. Die erste Anfrage nach einem Hochskalieren, einem Containerstart oder einer Leerlaufphase zahlt für Initialisierung, Verbindungsaufbau und Cache-Aufwärmung auf einmal.
- Echte Schwerarbeit bei einer Web-Anfrage. Berichtserstellung, Exporte, Bildverarbeitung oder Massenimporte, synchron abgewickelt, überschreiten irgendwann jedes vernünftige Timeout.
- Ressourcenkonkurrenz. CPU-Sättigung, Speicherdruck und Swapping machen jede Anfrage langsamer, die langsamsten überschreiten das Limit also zuerst.
- Zu knapp gesetzte Timeouts. Braucht ein Endpunkt legitim länger, als der Proxy erlaubt, ist die Konfiguration der Fehler, nicht der Code.
- Netzwerkprobleme zwischen den Stationen. Paketverlust oder Verzögerungen bei der DNS-Auflösung für die Upstream-Adresse fügen Latenz hinzu, die in den Anwendungszeiten nicht auftaucht.
So diagnostizieren und beheben Sie einen 504
- Messen Sie die Zeit bis zum Fehler. Die Verzögerung vor einem 504 entspricht meist dem konfigurierten Timeout, was Ihnen sagt, welche Station ihn erzeugt hat:
Ein 504 bei fast genau 60 Sekunden deutet auf ein Standard-Read-Timeout des Proxys hin. Einer bei 30 oder 100 Sekunden deutet auf die Komponente hin, die mit dieser Zahl konfiguriert ist, oft ein CDN statt Ihr eigener Proxy.curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" https://example.com/slow-page - Finden Sie heraus, ob es einen Endpunkt oder alle betrifft. Eine langsame URL ist ein Anwendungsproblem. Alles gleichzeitig langsam ist Ressourcensättigung oder eine ausfallende Abhängigkeit.
- Lesen Sie das Fehlerprotokoll des Proxys. Bei nginx ist die Zeile eindeutig:
Sie nennt den Upstream und die Phase, was einen langsamen Verbindungsaufbau von einer langsamen Antwort unterscheidet.[error] upstream timed out (110: Connection timed out) while reading response header from upstream, upstream: "http://127.0.0.1:8080/" - Messen Sie das Backend direkt, ohne den Proxy. Braucht dieselbe Anfrage gegen den Ursprung 90 Sekunden, meldet der Proxy die Wahrheit, und die Lösung gehört in die Anwendung.
- Profilen Sie den langsamen Pfad. Prüfen Sie das Slow-Query-Log, dann Anwendungs-Traces. Die meisten 504er führen auf eine einzelne Abfrage oder einen einzelnen ausgehenden Aufruf zurück.
- Beheben Sie die Ursache, nicht das Timeout. Fügen Sie den Index hinzu, cachen Sie das teure Ergebnis, oder verschieben Sie echte lange Arbeit in einen Hintergrundjob, der sofort antwortet und den Fortschritt separat meldet.
- Erhöhen Sie das Timeout nur, wenn die Arbeit legitim lange dauert, und tun Sie das konsistent auf jeder Station. Ein CDN-Limit von 30 Sekunden macht ein 120-Sekunden-Ursprungs-Timeout sinnlos.
- Setzen Sie Timeouts auf Ihre eigenen ausgehenden Aufrufe, damit eine langsame Abhängigkeit schnell mit einem klaren Fehler scheitert, statt einen Worker zu belegen, bis der Proxy aufgibt.
Die Antwortzeit ist die Frühwarnung
Ein 504 ist der Endzustand einer Verlangsamung, die sich eine Weile aufgebaut hat. Antwortzeiten driften von einer halben Sekunde auf zwei Sekunden auf zehn, und niemand bemerkt es, bis Anfragen das Limit überschreiten. Eine geplante HTTP-Prüfung zeichnet die Antwortzeit jeder Prüfung zusammen mit dem Statuscode auf, der Trend ist also lange vor dem ersten Timeout als Grafik sichtbar, und der Alarm kommt beim ersten echten Fehlschlag statt erst, wenn die Support-Warteschlange voll ist. Die Prüfung aus mehreren Regionen hilft ebenfalls, denn eine Route, die von einem Kontinent schnell und von einem anderen langsam ist, deutet auf den Netzwerkpfad oder die Edge-Konfiguration hin, nicht auf Ihre Datenbank.