Come posso risolvere gli errori di timeout con codice di stato HTTP 504 di Gateway API?

Breve descrizione

Quando una richiesta di integrazione richiede un tempo superiore al timeout massimo di integrazione della REST API di Gateway API, Gateway API restituisce un codice di stato HTTP 504.

Per risolvere gli errori di timeout 504 generati da Gateway API, prima di tutto identifica e verifica l'origine dell'errore nei log degli eventi di Amazon CloudWatch. Quindi utilizza uno dei seguenti metodi per ridurre il runtime delle richieste di integrazione fino a quando il timeout non si verifica più.

Puoi anche aumentare il timeout massimo di integrazione per le REST API Regionali e private oltre il limite predefinito di 29 secondi.

Risoluzione

Identificazione e verifica dell'origine dell'errore 504 in CloudWatch Logs

Completa i seguenti passaggi:

1. Per Rest API e API WebSocket, imposta la registrazione di Gateway API per gli errori 504. Per l'API HTTP, attiva la registrazione per scrivere i log in CloudWatch Logs.

2. Prova a riprodurre manualmente l'errore 504 nell'API.

3. Attiva la registrazione degli accessi per l'API. Quindi utilizza i segnaposto dei parametri seguenti per eseguire la diagnosi dell'origine dell'errore:

   $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.

   Per ulteriori informazioni, consulta Variabili di contesto per le trasformazioni dei dati.

4. Per filtrare il codice di stato "5##" nei log di accesso, utilizza la seguente query di CloudWatch Logs Insights:

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

5. Nella console CloudWatch, visualizza gli eventi del log di Gateway API per l'integrazione che riceve l'errore.

6. Tieni traccia dell'ID della richiesta in CloudWatch Logs. Se si verificano timeout nell'integrazione, dopo la riga Endpoint request body after transformations: compare il messaggio di errore "Execution failed due to a timeout". Per ulteriori informazioni, consulta Come faccio a trovare gli errori di REST API in API Gateway nei miei log di CloudWatch?

7. Per filtrare l'errore e selezionare il gruppo di log di esecuzione di API Gateway, utilizza la seguente query di CloudWatch Logs Insights:

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

8. Per determinare l'origine dell'errore, esamina i log del backend e verifica che sia stato invocato l'endpoint di integrazione associato.

9. Conferma il tempo impiegato dall'integrazione per completare il processo di richiesta e rispondi all'API Gateway.

10. Se l'integrazione non è stata invocata, implementa nuovi tentativi dell'API sul client. L'errore potrebbe derivare da un'interruzione temporanea della rete nel servizio API Gateway.
    Nota: assicurati che l'applicazione sia idempotente, in modo da evitare conflitti di dati quando riprovi a eseguire la richiesta API.

Se l'integrazione è stata invocata ma continua a restituire un messaggio di errore 504, riduci il runtime dell'integrazione.

Riduci il runtime dell'integrazione

Intraprendi le seguenti azioni:

• Assicurati che l'integrazione del backend includa solo la logica necessaria a Gateway API per inviare una risposta HTTP al client.
• Sposta qualsiasi logica non dipendente o di post-elaborazione in un altro servizio, ad esempio AWS Lambda.
• Se le latenze di rete causano l'errore 504, implementa una logica di nuovi tentativi nell'applicazione lato client.
• Segui le best practice per i prodotti e servizi AWS per migliorare le prestazioni di integrazione del backend.
• Configura l'invocazione asincrona della funzione Lambda del backend.

Aumenta il timeout massimo di integrazione per le API Regionali e private

Puoi inviare una richiesta di aumento della quota per aumentare la quota del timeout massimo di integrazione predefinita a più di 29 secondi per le API Regionali e private. Tuttavia, un aumento del timeout di integrazione potrebbe richiedere una riduzione della quota relativa alla limitazione (della larghezza di banda della rete) a livello di Regione per l'account AWS.

Nota: se aumenti il timeout massimo di integrazione, assicurati di sostituire il valore di timeout predefinito di 29 secondi con il nuovo valore. Ad esempio, modifica il valore di timeout predefinito di 29 secondi nelle integrazioni in cui desideri applicare l'aumento. Quindi ridistribuisci l'API affinché il nuovo timeout massimo di integrazione abbia effetto.

Informazioni correlate

Integrations for REST APIs in API Gateway (Integrazioni per REST API in API Gateway)

Set up a WebSocket API integration request in API Gateway (Configurazione di una richiesta di integrazione API WebSocket in API Gateway)

Creazione delle integrazioni per API HTTP in Gateway API

Come posso risolvere gli errori HTTP 504 da una REST API di Gateway API con un backend Lambda?