Wie behebe ich API-HTTP-504-Timeout-Fehler mit API Gateway?

Lesedauer: 4 Minute

Ich erhalte den Fehlerstatuscode HTTP 504, wenn ich meine REST-API, HTTP-API oder WebSocket-API mit Amazon API Gateway aufrufe.

Kurzbeschreibung

Wenn eine Integrationsanfrage länger dauert als der maximale Integrations-Timeout-Parameter deiner API Gateway REST-API, gibt API Gateway einen HTTP 504-Statuscode zurück.

Um 504-Timeout-Fehler von API Gateway zu beheben, musst du zunächst die Fehlerquelle in deinen Amazon-CloudWatch-Ereignisprotokollen identifizieren und überprüfen. Verwende anschließend eine oder mehrere der folgenden Methoden, um die Laufzeit deiner Integrationsanfragen zu reduzieren, bis keine Zeitüberschreitung mehr auftritt.

Lösung

Identifizierung und Überprüfung der Ursache des 504-Fehlers in CloudWatch-Protokollen

Führe die folgenden Schritte aus:

Richte für die REST-API und die WebSocket-API die API Gateway-Protokollierung für die 504-Fehler ein. Aktiviere für die HTTP-API die Protokollierung, um die Protokolle in die CloudWatch-Protokolle zu schreiben.
Versuche, den 504-Fehler in der API manuell zu reproduzieren.

Aktiviere die Zugriffsprotokollierung für die API. Verwende dann die folgenden Parameter-Platzhalter, um die Fehlerquelle zu diagnostizieren:

$context.integration.status: The status code returned from an integration. For AWS Lambda proxy integrations, this is the status code that your Lambda function code returns.
$context.integrationStatus: For Lambda proxy integration, this parameter represents the status code returned from Lambda, not from the backend Lambda function.
$context.integrationLatency: The integration latency in ms.

Weitere Informationen findest du unter $context-Variablen für Datenmodelle, Genehmiger, Zuweisungsvorlagen und CloudWatch-Zugriffsprotokollierung.

Verwende die folgende CloudWatch Log Insights-Abfrage, um den Statuscode „5XX“ aus den Zugriffsprotokollen zu filtern:

fields @timestamp, @message, @logStream
| filter status like '5'
| sort @timestamp desc
| display @timestamp,httpMethod,resourcePath,status,extendedRequestId,requestId

Zeige in der CloudWatch-Konsole die API Gateway-Protokollereignisse für die Integration an, bei der der Fehler aufgetreten ist.
Verfolge die Anfragen-ID in den CloudWatch-Protokollen. Wenn bei der Integration Zeitüberschreitungen auftreten, wird nach der Zeile „Endpunktanfragetext nach Transformationen:“ der Fehler „Execution failed due to a timeout“ angezeigt. Weitere Informationen findest du unter Wie finde ich API Gateway-REST-API-Fehler in meinen CloudWatch-Protokollen?

Verwende die folgende CloudWatch Log Insights-Abfrage, um den Fehler zu filtern und deine API Gateway-Ausführungsprotokollgruppe auszuwählen:

fields @timestamp, @message
|filter @message like "Execution failed due to a timeout error"
|sort @timestamp desc

Um die Fehlerquelle zu ermitteln, überprüfe die Backend-Protokolle und stelle sicher, dass der zugehörige Integrationsendpunkt aufgerufen wurde.
Überprüfe, wie lange die Integration gedauert hat, um den Anfrageprozess abzuschließen und an API Gateway zu antworten.
Wenn die Integration nicht aufgerufen wurde, implementiere API-Wiederholungen auf dem Client. Der Fehler kann auf einen temporären Netzwerkfehler im API Gateway-Service zurückzuführen sein.
Hinweis: Stelle sicher, dass die Anwendung idempotent ist, damit du Datenkonflikte vermeidest, wenn du die API-Anfragen erneut versuchst.
-oder-
Wenn die Integration aufgerufen wurde, aber immer noch eine 504-Fehlermeldung zurückgibt, versuche, die Laufzeit der Integration zu reduzieren. Wenn es sich um eine HTTP-API handelt, versuche, den Timeout-Parameter für maximale Integrationsanfragen zu erhöhen. Weitere Informationen findest du unter Erhöhung des Timeout-Grenzwerts für die Amazon API Gateway-Integration auf über 29 Sekunden.

Hinweis: Die standardmäßige maximale Dauer des Integrations-Timeouts der API Gateway-REST-API beträgt 29 Sekunden. Für die HTTP-API kann die Zeitüberschreitung bis zu einem Höchstwert von 30 Sekunden konfiguriert werden.

So reduzierst du die Laufzeit der Integration

Ergreife eine oder mehrere der folgenden Maßnahmen:

Stelle sicher, dass die Backend-Integration nur die Logik enthält, die für API Gateway erforderlich ist, um eine HTTP-Antwort an den Client zu senden.
Verschiebe jede unabhängige Logik oder Logik nach der Verarbeitung in einen anderen Service, wie z. B. AWS Lambda.
Wenn Netzwerklatenzen den 504-Fehler verursachen, implementiere die Wiederholungslogik in der clientseitigen Anwendung.
Befolge bewährte Methoden für die AWS-Produkte und -Services, um die Leistung der Backend-Integration zu verbessern.
Richte den asynchronen Aufruf der Backend-Lambda-Funktion ein.