¿Cómo soluciono los errores de tiempo de espera del código de estado HTTP 504 de API Gateway?

Descripción corta

Cuando una solicitud de integración tarda más que el parámetro de tiempo de espera de integración máximo de la API configurada de API Gateway, esta última devuelve un código de estado HTTP 504.

Para solucionar los errores de tiempo de espera 504 de API Gateway, primero identifica y verifica el origen del error en los registros de eventos de Amazon CloudWatch. A continuación, usa uno o más de los siguientes métodos para reducir el tiempo de puesta en marcha de las solicitudes de integración hasta que no se agote el tiempo de espera.

También puedes aumentar el límite de tiempo de espera de integración para las API de REST regionales y privadas por encima del límite predeterminado de 29 segundos.

Resolución

Identificación y verificación del origen del error 504 en los registros de CloudWatch

Sigue estos pasos:

1. Para la API de REST y la API de Websocket, configura el registro de API Gateway para los errores 504. Para la API HTTP, activa el registro para escribirlos en los registros de CloudWatch.

2. Intenta reproducir manualmente el error 504 en la API.

3. Activa el registro de acceso para la API. A continuación, usa los siguientes marcadores de posición de parámetros para diagnosticar el origen del error:

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

   Para más información, consulta Variables de contexto para transformaciones de datos.

4. Usa la siguiente consulta de Información de registros de CloudWatch para filtrar el código de estado «5##» de los registros de acceso:

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

5. En la consola de CloudWatch, consulta los eventos de registro de API Gateway de la integración que recibe el error.

6. Haz un seguimiento del id. de la solicitud en los registros de CloudWatch. Si hay tiempos de espera en la integración, aparecerá el error «Execution failed due to a timeout» después de la frase Endpoint request body after transformations. Para obtener más información, consulta ¿Cómo puedo encontrar los errores de la API de REST de la API Gateway en los registros de CloudWatch?

7. Para filtrar el error y seleccionar el grupo de registros de puesta en marcha de API Gateway, utiliza la siguiente consulta de Información de registros de CloudWatch:

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

8. Para determinar el origen del error, revisa los registros del backend y verifica que se haya invocado el punto de enlace de integración asociado.

9. Confirma cuánto tiempo ha tardado la integración en completar el proceso de solicitud y responder a API Gateway.

10. Si no se ha invocado la integración, implementa los reintentos de la API en el cliente. El error puede deberse a un fallo temporal de la red en el servicio de API Gateway.
    Nota: Asegúrate de que tu aplicación sea idempotente para evitar conflictos de datos cuando vuelvas a intentar enviar la solicitud de la API.

Si se ha invocado la integración, pero aun así aparece el mensaje de error 504, intenta reducir el tiempo de puesta en marcha de la integración.

Reducción del tiempo de puesta en marcha de la integración

Haz lo siguiente:

• Asegúrate de que tu integración de backend incluya solo la lógica necesaria para que API Gateway envíe una respuesta HTTP al cliente.
• Traslada cualquier lógica no dependiente o de posprocesamiento a otro servicio, como AWS Lambda.
• Si las latencias de la red están causando el error 504, implementa la lógica de reintento en la aplicación del cliente.
• Sigue las prácticas recomendadas para tus productos y servicios de AWS para mejorar el rendimiento de la integración del backend.
• Configura la invocación asíncrona de la función de Lambda del backend.

Aumenta el límite de tiempo de espera de integración para las API regionales y privadas

Puedes enviar una solicitud de cuota para aumentar el límite de tiempo de espera de integración predeterminado a más de 29 segundos para las API regionales y las API privadas. Sin embargo, un aumento del tiempo de espera de la integración puede requerir una reducción de la cuota de aceleración a nivel regional para tu cuenta de AWS.

Nota: Si aumentas el límite de tiempo de espera de la integración, asegúrate de cambiar el valor de tiempo de espera predeterminado de 29 segundos por el nuevo valor. Por ejemplo, cambia el valor de tiempo de espera predeterminado de 29 segundos en las integraciones en las que quieras aplicar el aumento. A continuación, vuelve a implementar la API para activar el nuevo límite de tiempo de espera de la integración.

Información relacionada

Integraciones para las API de REST en API Gateway

Configuración de una solicitud de integración de API de WebSocket en API Gateway

Creación de integraciones para las API de HTTP en API Gateway

¿Cómo soluciono errores HTTP 504 desde una API de REST de API Gateway con un backend de Lambda?