How can I troubleshoot API HTTP 504 timeout errors with API Gateway?

Last updated: 2022-08-17

I receive an HTTP 504 error status code when I invoke my REST API, HTTP API or Websocket API using Amazon API Gateway. How do I troubleshoot this error?

Short description

If an integration request takes longer than your API Gateway REST 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 execution logs. Then, use one or more of the following methods to reduce the runtime of your integration requests until they don't timeout.

Resolution

To identify and verify the source of the 504 error in your Amazon CloudWatch logs

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

2.    Manually try to reproduce the 504 error in the API.

3.    In the CloudWatch console, view the API Gateway execution logs for the integration receiving the error.

4.    Track the request ID in your CloudWatch logs. If there are timeouts on the integration, you see an Execution failed due to a timeout error 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?

5.    Activate access logging for the API and use the following parameter variables to diagnose the source of error:

$context.integration.status: The status code returned from an integration. For 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 AWS Lambda, not from the backend Lambda function.
$context.integrationLatency: The integration latency in ms.

For more information, see $context Variables for data models, authorizers, mapping templates, and CloudWatch access logging.

6.    Determine the source of the error by doing the following:

Verify that the associated integration endpoint was invoked.

Confirm how long the integration took to complete the processing of request and correspondingly respond to API Gateway.

7.    If the integration wasn't invoked, retry the request. (The error might have resulted from a temporary network failure in the API Gateway service.)
Note: Make sure that your application is idempotent. This avoids data conflicts when you retry the API request.

-or-

If the integration was invoked but still returned a 504 error message, try reducing your integration's runtime. If it's an HTTP API, you can try increasing your maximum integration request timeout parameter.

Note: API Gateway REST API's default maximum integration timeout is 29 seconds. For HTTP API the timeout can be configured for up to the maximum value of 30 seconds.

To reduce your integration's runtime

  • Make sure that your backend integration includes only the logic needed for API Gateway to send an HTTP response to the client. Consider moving any non-dependent or post-processing logic to another service, such as AWS Lambda
  • If network latencies are causing the 504 error, implement retry logic on the client-side application.
  • Improve the backend integration performance by following the optimization best practices for your platform.
  • Consider setting up asynchronous invocation of the backend Lambda function.