HTTP Statuscode 504: Gateway Timeout

Der HTTP-Statuscode 504 ist der einzige der 5xx-Familie, der eine konkrete Aussage über die Ursache trifft: Es hat zu lange gedauert.

RFC 9110 beschreibt 504 „Gateway Timeout" als Antwort eines Servers, der als Gateway oder Proxy arbeitet und innerhalb der eingeräumten Zeit keine rechtzeitige Antwort vom vorgelagerten Server erhalten hat. Anders als bei 500 steht damit fest, wonach zu suchen ist. Nicht nach einem Absturz, sondern nach etwas Langsamem.

Der entscheidende Unterschied zu 502#

Beide Codes kommen von einem Proxy, beide betreffen die Übergabe an einen vorgelagerten Dienst. Die Unterscheidung liegt darin, was der Proxy gesehen hat.

• 502 — es kam eine ungültige oder gar keine Antwort. Die Verbindung wurde abgelehnt oder brach ab.
• 504 — die Verbindung stand, der Upstream hat sie angenommen und nur nicht rechtzeitig geliefert.

Das ist mehr als eine Feinheit. Eine 502 wirft die Frage auf, ob der Dienst überhaupt läuft. Eine 504 bestätigt, dass er läuft — und dass er an einer Aufgabe hängt, die länger dauert als vorgesehen. In den Prozesslisten des Anwendungsservers ist die betroffene Anfrage während des Vorfalls oft noch sichtbar, weil sie weiterrechnet, nachdem der Proxy bereits aufgegeben hat.

Ein Nebeneffekt daraus: Der Vorgang wird nicht zwingend abgebrochen. Bei einem 504 während eines Imports oder einer Bestellung kann die Verarbeitung im Hintergrund vollständig durchlaufen, obwohl der Besucher eine Fehlerseite sieht. Doppelte Datensätze nach einem vermeintlich fehlgeschlagenen Vorgang haben regelmäßig genau diese Ursache.

Welche Zeitgrenze zuerst greift#

In einer typischen Kette wacht mehr als eine Uhr, und die kürzeste gewinnt.

Der Proxy. Bei nginx sind das proxy_read_timeout für weitergereichte HTTP-Anfragen und fastcgi_read_timeout für PHP-FPM. Beide zählen die Zeit zwischen zwei aufeinanderfolgenden Datenpaketen, nicht die Gesamtdauer der Anfrage. Eine Antwort, die kontinuierlich Daten sendet, läuft deshalb nicht ab, auch wenn sie insgesamt lange braucht.

Der Anwendungsprozess. PHP-FPM kennt request_terminate_timeout, PHP selbst max_execution_time. Greift die PHP-Grenze zuerst, endet die Anfrage mit einem fatalen Fehler und einer Antwort — dann sieht der Besucher keine 504.

Die Datenbank. Sperren und Wartezeiten haben eigene Grenzwerte. Wartet eine Abfrage auf eine gesperrte Zeile, gibt es dort weder Fehler noch Fortschritt.

Vorgelagerte Dienste. CDN und Loadbalancer bringen eigene, oft nicht veränderbare Grenzen mit. Eine Anfrage, die intern sauber durchläuft, kann von außen trotzdem in einer 504 enden.

Daraus ergibt sich die häufigste Fehlbedienung: Es wird der falsche Wert erhöht. Wer max_execution_time anhebt, während fastcgi_read_timeout niedriger liegt, ändert nichts am Ergebnis. Sinnvoll ist es, die Werte in der Kette aufeinander abzustimmen und die Anwendungsgrenze knapp unterhalb der Proxygrenze zu halten, damit die Anwendung noch selbst abbrechen und eine verwertbare Fehlermeldung protokollieren kann.

Wo die Zeit tatsächlich verloren geht#

Die Grenze anzuheben verschiebt das Problem nur. Interessanter ist, worauf gewartet wird.

Langsame Datenbankabfragen. Der mit Abstand häufigste Fall. Verantwortlich sind meist fehlende Indizes auf Spalten, nach denen gefiltert oder sortiert wird, Abfragen über Tabellen, die mit den Jahren gewachsen sind, oder Suchabfragen mit führendem Platzhalter, die keinen Index nutzen können. Das Slow-Query-Log von MySQL oder MariaDB benennt die betroffenen Abfragen samt Laufzeit; EXPLAIN zeigt anschließend, ob ein Index verwendet wird.

Externe Aufrufe im Seitenaufbau. Eine Schnittstelle, eine Lizenzprüfung, ein Zahlungsdienst: Antwortet ein fremder Dienst langsam und ist im Code keine kurze Zeitgrenze gesetzt, wartet die eigene Seite mit. Solche Aufrufe gehören nicht in den synchronen Seitenaufbau.

Sperren in der Datenbank. Eine lange schreibende Transaktion blockiert andere. Die Symptome treten dann nicht auf einer bestimmten Seite auf, sondern in Wellen über die gesamte Anwendung.

Aufgaben, die in einen Hintergrundprozess gehören. Importe, Exporte, Bildverarbeitung, Berichte. Alles, was in Minuten statt Sekunden rechnet, sollte über eine Warteschlange laufen und dem Besucher einen Status zurückgeben, statt die Verbindung offenzuhalten.

Was 504 nach außen auslöst#

Anhaltende 504-Antworten haben Wirkungen über den Ausfall hinaus. Suchmaschinen werten 5xx-Antworten als vorübergehende Serverprobleme, drosseln bei Häufung das Crawling des betroffenen Hosts und können Seiten, die wiederholt im Fehlerzustand abgerufen wurden, aus dem Index nehmen. Der Zusammenhang und die Diagnose dazu stehen in Warum Google Seiten nicht indexiert.

Tritt die Zeitüberschreitung nur an einzelnen Stellen auf, etwa im Backend oder bei einer bestimmten Auswertung, ist das ein Hinweis auf eine konkrete Abfrage und kein Kapazitätsproblem. Tritt sie unter Last überall auf, ist es umgekehrt. Zeigt sich beim Nachsehen, dass eine Anwendung gar keine Verbindung zur Datenbank mehr aufbaut, gilt ein anderer Weg: Fehler beim Aufbau einer Datenbankverbindung.