← Zurück zur Kategorie
API Gateway liefert HTTP 503 oder Timeout
Prüfe zuerst, ob das Zielsystem hinter dem API Gateway erreichbar und gesund ist. HTTP 503 und Timeouts entstehen in diesem Themenbereich meist durch nicht erreichbare, überlastete oder als unhealthy bewertete Upstream-Targets sowie durch fehlerhafte Routing- oder Änderungszustände.
Ein API Gateway im API-Management liefert für einen Endpunkt HTTP 503 Service Unavailable oder meldet einen Timeout. Der Aufruf wird im Monitoring oder im Gateway als Down markiert, obwohl die Ursache häufig im angebundenen Zielsystem, in dessen Erreichbarkeit, in Health Checks oder in einer jüngsten Konfigurationsänderung liegt.
- Der API-Gateway-Check zeigt den Zustand Down
- Der Aufruf endet mit HTTP 503 Service Unavailable
- Ein Endpunkt antwortet nicht innerhalb des erwarteten Zeitfensters
- Es erscheint eine Timeout-Meldung im Bereich des Gateways oder des Monitoring
- Health Checks des Zielsystems schlagen fehl oder wechseln zwischen healthy und unhealthy
- Nach Änderungen an Routing oder Backend-Verhalten treten die Fehler erstmals auf
- Upstream-Target ist nicht erreichbar oder wird vom API Gateway als unhealthy bewertet (inferred): Die 503-Meldung passt zu einem Gateway, das kein gesundes Zielsystem findet oder ein Ziel wegen fehlgeschlagener Health Checks als nicht verfügbar einstuft.
- Backend antwortet zu langsam und überschreitet das Gateway-Timeout (inferred): Die Timeout-Signatur deutet darauf hin, dass der Backend-Call die zulässige Antwortzeit überschreitet oder dauerhaft hängt.
- Letzte Änderung an Routing, Mapping, Rewrite, Authentisierung oder Zertifikaten beeinflusst den Aufrufpfad (inferred): Bei Gateway-Fehlern ist eine jüngste Konfigurationsänderung ein wichtiger Prüfpfad, wenn der Endpunkt vorher funktioniert hat.
- Backend-Ressourcen sind erschöpft oder der Dienst befindet sich in einem fehlerhaften Laufzeitzustand (inferred): Überlastung, Crashloops oder blockierte Abhängigkeiten können sowohl 503 als auch Timeouts auslösen.
- Betroffenen Endpunkt und Fehlerbild eingrenzen — Identifiziere den betroffenen Gateway-Endpunkt, den Zeitpunkt des Fehlers und die genaue Fehlerausprägung. Prüfe, ob der Fehler konstant auftritt oder nur einzelne Aufrufe betrifft. Checks: Betroffene Route, Uhrzeit und Fehlermeldung aus Monitoring oder Ticket übernehmen; Prüfen, ob nur ein einzelner Endpunkt oder mehrere Routen betroffen sind; Status des Endpunkts im Gateway-Monitoring vergleichen
- Zielsystem direkt prüfen — Teste das Backend oder den Upstream außerhalb des Gateways, um zu klären, ob das Problem im Zielsystem selbst liegt oder erst auf Gateway-Ebene sichtbar wird. Checks: Health-Endpoint des Zielsystems prüfen; Direkte Antwortzeit und Statuscodes des Zielsystems prüfen; Vergleichen, ob das Zielsystem direkt erfolgreich antwortet, während das Gateway Fehler meldet
- Gateway-Health-Status und Upstream-Verfügbarkeit prüfen — Bewerte, ob das Gateway die Upstream-Targets als healthy erkennt und ob alle erwarteten Hosts erreichbar sind. Checks: Health-Status der Upstream-Targets im Gateway prüfen; Prüfen, ob ein Target als down, unhealthy oder nicht verfügbar markiert ist; Abgleichen, ob Health-Checks kürzlich fehlgeschlagen sind
- Letzte Änderungen rückverfolgen — Wenn der Fehler neu ist, prüfe jüngste Änderungen an Gateway, Backend oder Abhängigkeiten. Dazu gehören Routing, Kontextpfade, Rewrite-Regeln, Authentisierung, Zertifikate und Deployments. Checks: Letzte Deployments oder Konfigurationsänderungen am Gateway und Backend prüfen; Routing- und Mapping-Änderungen vergleichen; Prüfen, ob eine Änderung zeitlich mit dem Fehlerbeginn zusammenfällt
- Backend-Engpässe beheben — Wenn das Zielsystem langsam oder blockiert ist, behebe die Ursache im Backend. Dazu gehören Ressourcengrenzen, fehlerhafte Abhängigkeiten, langsame Datenzugriffe oder ein instabiler Dienstzustand. Checks: Auslastung von CPU, Speicher, Verbindungen und Warteschlangen prüfen; Langsame Abfragen oder externe Abhängigkeiten identifizieren; Falls nötig, den betroffenen Dienst kontrolliert neu starten oder fehlerhafte Targets ersetzen
- Gateway nach der Behebung erneut testen — Nachdem das Zielsystem stabil ist, teste den Endpunkt erneut und prüfe, ob das Gateway wieder erfolgreiche Antworten liefert und der Down-Zustand verschwindet. Checks: Endpunkt erneut über das Gateway aufrufen; Statuscode und Antwortzeit prüfen; Verifizieren, dass kein 503 und kein Timeout mehr auftritt
- Der Endpunkt antwortet wieder erfolgreich über das API Gateway
- Der Gateway-Status wechselt von Down auf Up oder Healthy
- Es treten keine wiederkehrenden 503- oder Timeout-Meldungen mehr auf
- Die Antwortzeit bleibt unter dem zulässigen Zeitlimit
- Die Health Checks des Zielsystems sind stabil erfolgreich
- Wenn das Zielsystem direkt ebenfalls fehlschlägt, ist die Zuständigkeit auf das Backend- oder Service-Team zu legen.
- Wenn der Fehler nach Rollback, Restart oder Health-Check-Korrektur bestehen bleibt, sind Gateway-Konfiguration und Upstream-Kopplung tiefer zu prüfen.
- Wenn DNS-, TLS- oder Authentisierungsprobleme auftreten, sollte auf den passenden Fachbereich mit dem konkreten Fehlerbild eskaliert werden.
- Bei wiederkehrenden Timeouts trotz gesunder Zielsysteme müssen Last, Abhängigkeiten und Timeout-Vorgaben gemeinsam analysiert werden.
- In den ausgewerteten Tickets ist keine eindeutig dokumentierte Root Cause belegt.
- Der Artikel beschreibt deshalb einen Prüf- und Wiederherstellungsweg, keine sicher bestätigte Einzelursache.
- Wenn der Fehler nicht auf Upstream-Verfügbarkeit oder Antwortzeit zurückzuführen ist, ist ein anderes Diagnoseverfahren erforderlich.
Fragen & Antworten
Warum liefert mein API Gateway HTTP 503 oder einen Timeout, obwohl der Endpunkt vorher funktioniert hat?
Prüfe zuerst das Zielsystem hinter dem Gateway. HTTP 503 und Timeouts entstehen in diesem Szenario meist, weil das Upstream-Target nicht erreichbar, zu langsam oder vom Gateway als unhealthy bewertet wird. Eine jüngste Änderung an Routing, Mapping, Authentisierung oder Zertifikaten ist ebenfalls ein häufiger Auslöser.
- Betroffenen Endpunkt und Zeitpunkt des Fehlers eingrenzen und prüfen, ob nur eine Route oder mehrere betroffen sind.
- Den Upstream oder das Backend direkt testen, um zu sehen, ob es außerhalb des Gateways ebenfalls fehlschlägt oder nur über das Gateway auffällt.
- Den Health-Status der Upstream-Targets im Gateway-Monitoring prüfen und kontrollieren, ob Targets als down, unhealthy oder nicht verfügbar markiert sind.
- Jüngste Änderungen an Gateway, Backend und Abhängigkeiten rückverfolgen, insbesondere Routing, Kontextpfade, Rewrite-Regeln, Authentisierung und Zertifikate.
- Wenn das Backend selbst langsam oder instabil ist, Engpässe wie CPU, Speicher, Verbindungen, Warteschlangen und langsame Abhängigkeiten prüfen und beheben.
- Der Endpunkt antwortet wieder erfolgreich über das API Gateway.
- Der Status wechselt im Monitoring von Down auf Up oder Healthy.
- Es treten keine wiederkehrenden 503- oder Timeout-Meldungen mehr auf.
- Die Antwortzeit bleibt im erwarteten Zeitfenster.
Wenn das Backend auch direkt fehlschlägt, ist das an das zuständige Backend- oder Service-Team zu eskalieren. Bleibt der Fehler nach Korrektur von Health Checks, Restart oder Rollback bestehen, muss die Gateway-Konfiguration und die Upstream-Kopplung tiefer geprüft werden. Bei DNS-, TLS- oder Authentisierungsfehlern ist an den passenden Fachbereich mit dem konkreten Fehlerbild zu übergeben.
Wie prüfe ich, ob der Fehler im Backend liegt oder erst am API Gateway entsteht?
Teste das Zielsystem direkt außerhalb des Gateways. Wenn das Backend direkt erfolgreich antwortet, aber über das Gateway 503 oder Timeouts liefert, liegt die Ursache eher in Gateway-Health, Routing oder Konfiguration. Wenn das Backend direkt ebenfalls fehlschlägt, ist die Ursache wahrscheinlich im Zielsystem selbst.
- Den betroffenen Endpunkt und die genaue Fehlerausprägung aus Monitoring oder Betriebsmeldung übernehmen.
- Das Backend direkt auf Erreichbarkeit und Antwortverhalten prüfen, idealerweise über den vorgesehenen Health-Endpoint oder einen vergleichbaren Prüfpunkt.
- Antwortzeit und Statuscode des Backends mit dem Verhalten über das Gateway vergleichen.
- Prüfen, ob nur der Gateway-Aufruf fehlschlägt oder ob auch direkte Aufrufe an das Zielsystem langsam oder fehlerhaft sind.
- Falls direkt bereits Fehler auftreten, Ursache im Backend, in Abhängigkeiten oder in der Infrastruktur weiter eingrenzen.
- Direktaufruf und Gateway-Aufruf lassen sich sauber vergleichen.
- Das Verhalten zeigt eindeutig, ob die Störung vor oder hinter dem Gateway entsteht.
- Die Ursache ist einem klaren Bereich zugeordnet: Backend, Gateway oder Abhängigkeit.
Wenn der direkte Test keine Klarheit bringt, müssen zusätzliche Beobachtungen wie Logs, Monitoring und letzte Änderungen herangezogen werden. Bei direkten Backend-Fehlern ist die Zuständigkeit nicht mehr primär beim API-Gateway-Betrieb, sondern beim Service- oder Plattformteam.
Was bedeutet es, wenn ein API-Gateway-Check auf Down steht und Health Checks zwischen healthy und unhealthy wechseln?
Das Gateway bewertet mindestens ein Upstream-Target als instabil oder nicht zuverlässig erreichbar. Ein wechselnder Health-Status ist ein starker Hinweis auf Erreichbarkeitsprobleme, Überlastung, fehlerhafte Abhängigkeiten oder eine unpassende Health-Check-Konfiguration.
- Den betroffenen Gateway-Endpunkt und den Zeitpunkt des Statuswechsels identifizieren.
- Den Health-Status der Upstream-Targets im Gateway prüfen und feststellen, ob alle erwarteten Ziele verfügbar sind.
- Verifizieren, ob der Health-Endpoint des Zielsystems direkt stabil antwortet oder selbst schwankt.
- Prüfen, ob kürzlich Änderungen an Backend-Verhalten, Routing oder Health-Check-Bedingungen vorgenommen wurden.
- Wenn der Health-Status instabil bleibt, Backend-Ressourcen, abhängige Dienste und Laufzeitzustand untersuchen.
- Der Status bleibt stabil auf Healthy oder Up.
- Health-Checks schlagen nicht mehr wiederholt fehl.
- Der Endpunkt wird vom Gateway wieder zuverlässig erreicht.
Wenn ein Zielsystem direkt instabil ist, gehört die Analyse an das zuständige Service-Team. Wenn nur ein bestimmtes Target fehlschlägt, aber andere Targets stabil bleiben, ist die Ursache gezielt im betroffenen Backend oder in der Kopplung zu suchen.
Welche Prüfungen sind nach einer Routing-, Mapping- oder Zertifikatsänderung bei 503 oder Timeout sinnvoll?
Wenn der Fehler nach einer Änderung erstmals auftritt, prüfe zuerst den kompletten Aufrufpfad. Routing, Kontextpfade, Rewrite-Regeln, Authentisierung und Zertifikate können dazu führen, dass das Gateway kein gültiges oder rechtzeitig antwortendes Upstream-Ziel mehr erreicht.
- Den Zeitpunkt des Fehlerbeginns mit der Änderung am Gateway oder Backend abgleichen.
- Prüfen, ob sich Routing, Kontextpfad, Mapping oder Rewrite-Regeln verändert haben und ob der Aufruf noch auf das erwartete Ziel zeigt.
- Authentisierung und Zertifikate prüfen, falls der Aufrufpfad oder die Absicherung des Zielsystems geändert wurde.
- Verifizieren, ob nach der Änderung Health Checks weiterhin korrekt greifen oder ob Targets fälschlich als unhealthy erscheinen.
- Bei Verdacht auf die Änderung eine kontrollierte Rücknahme oder einen Vergleich mit dem vorherigen Zustand durchführen.
- Der Fehlerzeitpunkt korreliert nicht mehr mit einer aktuellen Änderung oder wurde durch die Korrektur beseitigt.
- Der Endpunkt erreicht wieder das korrekte Zielsystem.
- Health Checks und Gateway-Status sind stabil.
Wenn die Änderung nicht eindeutig ursächlich ist, müssen Backend-Verhalten und Infrastruktur ebenfalls betrachtet werden. Bei Problemen mit DNS, TLS oder Authentisierung sollte an den dafür zuständigen Fachbereich mit dem konkreten Symptom eskaliert werden.
Wie gehe ich vor, wenn das Backend zu langsam ist und das Gateway deshalb 503 oder Timeout liefert?
Wenn das Backend die erwartete Antwortzeit überschreitet, meldet das Gateway häufig Timeout oder 503. Dann musst du die Ursache im Zielsystem suchen, etwa bei Überlastung, langsamen Abfragen, blockierten Abhängigkeiten oder einem fehlerhaften Laufzeitzustand.
- Prüfen, ob die Antwortzeit des Backends direkt auffällig hoch ist oder der Dienst zeitweise nicht reagiert.
- Systemressourcen wie CPU, Speicher, Verbindungen und Warteschlangen auf Engpässe prüfen.
- Langsame Abfragen, blockierte externe Abhängigkeiten oder wiederholte Fehlversuche identifizieren.
- Den betroffenen Dienst kontrolliert stabilisieren, zum Beispiel durch Behebung des Engpasses oder einen geplanten Neustart, falls das Betriebsmodell das vorsieht.
- Nach der Stabilisierung den Endpunkt erneut über das Gateway testen.
- Die Antwortzeit liegt wieder im erwarteten Bereich.
- Das Gateway liefert wieder erfolgreiche Antworten statt Timeout oder 503.
- Es gibt keine wiederkehrenden Auslastungs- oder Blockadehinweise mehr.
Wenn die Ursache in einer externen Abhängigkeit liegt, muss diese separat behandelt werden. Bleibt die Überlast trotz Maßnahmen bestehen, ist das an das Backend-, Plattform- oder Infrastrukturteam zu übergeben.
Was mache ich, wenn der Endpunkt direkt funktioniert, aber über das Gateway weiter 503 oder Timeout kommt?
Dann liegt die Ursache wahrscheinlich nicht im reinen Backend-Betrieb, sondern im Gateway-Pfad, in der Upstream-Zuordnung oder in der Kopplung zwischen Gateway und Zielsystem. Prüfe, ob das Gateway das Zielsystem als healthy erkennt und ob die letzte Konfiguration korrekt ist.
- Direkten Backend-Test und Gateway-Aufruf zeitnah vergleichen.
- Im Gateway-Monitoring prüfen, ob das Upstream-Target als down, unhealthy oder nicht verfügbar markiert ist.
- Health-Checks des Zielsystems kontrollieren und auf Fehlerspitzen oder Schwankungen achten.
- Letzte Änderungen an Routing, Mapping, Rewrite, Authentisierung oder Zertifikaten gegenprüfen.
- Wenn das Backend direkt stabil ist, aber das Gateway weiter scheitert, die Gateway-Konfiguration und die Upstream-Verknüpfung detailliert analysieren.
- Gateway und direkter Zugriff zeigen konsistentes Verhalten.
- Der Gateway-Status ist wieder Healthy.
- 503- und Timeout-Meldungen treten nicht mehr auf.
Wenn die Ursache nicht in Gateway-Health, Konfiguration oder Upstream-Zuordnung liegt, müssen tiefergehende Analysen in den zuständigen Fachbereichen erfolgen. DNS-, TLS- und Authentisierungsprobleme gehören an den jeweiligen Spezialbereich.
Wann sollte ich einen 503- oder Timeout-Fall im API Gateway an ein anderes Team eskalieren?
Eskalieren solltest du dann, wenn die Ursache außerhalb des Gateway-Betriebs liegt oder die grundlegenden Maßnahmen keine Besserung bringen. Das gilt besonders, wenn das Backend direkt ebenfalls fehlschlägt, wenn DNS-, TLS- oder Authentisierungsprobleme vorliegen oder wenn Timeouts trotz gesunder Zielsysteme weiter auftreten.
- Prüfen, ob der Fehler direkt am Backend ebenfalls auftritt.
- Testen, ob ein Rollback, ein Restart oder eine Health-Check-Korrektur den Zustand verbessert hat.
- Wenn der Fehler bleibt, Gateway-Konfiguration, Upstream-Kopplung und jüngste Änderungen erneut bewerten.
- Bei Zusatzsymptomen wie DNS-, TLS- oder Authentisierungsfehlern den passenden Fachbereich gezielt ansprechen.
- Für die Übergabe das konkrete Fehlerbild, Zeitpunkt, betroffene Route und die bereits geprüften Punkte dokumentieren.
- Der Fall ist einem zuständigen Team klar zugeordnet.
- Alle bereits geprüften Punkte sind nachvollziehbar dokumentiert.
- Es ist klar, ob Backend, Gateway oder Infrastruktur weiter bearbeitet werden muss.
Wenn die Ursache nicht isoliert werden kann oder mehrere Schichten betroffen sind, ist eine gemeinsame Analyse von Gateway, Backend und Infrastruktur notwendig. Dieser Artikel liefert dann nur den Erstprüfpfad, nicht die vollständige Root-Cause-Analyse.