I received an HTTP 504 error status code when I used Amazon API Gateway to invoke my REST API, HTTP API, or WebSocket API.

Short description

When an integration request takes longer than your configured API Gateway API maximum integration timeout parameter, API Gateway returns an HTTP 504 status code.

To troubleshoot 504 timeout errors from API Gateway, first identify and verify the source of the error in your Amazon CloudWatch event logs. Then, use one of the following methods to reduce the runtime of your integration requests until they no longer time out.

You can also increase the integration timeout limit for Regional and private REST APIs greater than the default limit of 29 seconds.

Resolution
Identify and verify the source of the 504 error in your CloudWatch logs

Complete the following steps:

For Rest API and WebSocket API, set up API Gateway logging for the 504 errors. For HTTP API, activate logging to write logs to CloudWatch logs.


Manually try to reproduce the 504 error in the API.


Activate access logging for the API. Then, then use the following parameter placeholders to diagnose the source of 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.

For more information, see Context variables for data transformations.


To filter the “5##” status code from access logs, use the following CloudWatch Log Insights query:



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



In the CloudWatch console, view the API Gateway log events for the integration that receives the error.


Track the request ID in your CloudWatch logs. If there are timeouts on the integration, then an “Execution failed due to a timeout” error appears after the Endpoint request body after transformations: line. For more information, see How do I find API Gateway REST API errors in my CloudWatch logs?


To filter the error and select your API Gateway execution log group, use the following CloudWatch Log Insights query:



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



To determine the source of the error, review the backend logs and verify that the associated integration endpoint was invoked.


Confirm how long the integration took to complete the request process and respond to API Gateway.


If the integration wasn’t invoked, then implement API retries on the client. The error might result from a temporary network failure in the API Gateway service. Note: Make sure that your application is idempotent so that you avoid data conflicts when you retry the API request.

If the integration was invoked but still returns a 504 error message, then reduce your integration’s runtime.

Reduce your integration’s runtime

Complete the following actions:

Make sure that your backend integration includes only the logic needed for API Gateway to send an HTTP response to the client.
Move any non-dependent or post-process logic to another service, such as AWS Lambda.
If network latencies cause the 504 error, then implement retry logic on the client-side application.
Follow the best practices for your AWS products and services to improve the backend integration performance.
Set up asynchronous invocation of the backend Lambda function. Increase the integration timeout limit for Regional and private APIs

You can submit a quota request to increase the default integration timeout limit quota to greater than 29 seconds for Regional APIs and private APIs. However, an integration timeout increase might require a reduction in your Region-level throttle quota for your AWS account.

Note: If you increase the integration timeout limit, then make sure that you change the default timeout value of 29 seconds to the new value. For example, change the default timeout value of 29 seconds in the integrations where you want to apply the increase. Then, redeploy the API for the new integration timeout limit to take effect.

Related information

Integrations for REST APIs in API Gateway

Set up a WebSocket API integration request in API Gateway

Create integrations for HTTP APIs in API Gateway

How do I troubleshoot HTTP 504 errors from an API Gateway REST API with a Lambda backend?