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

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

Short descriptionIf 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.

ResolutionTo identify and verify the source of the 504 error in your Amazon CloudWatch logs1.    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.    Activate access logging for the API and then use the following parameter variables 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 models, authorizers, mapping templates, and CloudWatch access logging.4.    Use the following CloudWatch Log Insights query to filter the ‘5XX’ status code from access logs:fields @timestamp, @message, @logStream| filter status like ‘5’| sort @timestamp desc| display @timestamp,httpMethod,resourcePath,status,extendedRequestId,requestId5.    In the CloudWatch console, view the API Gateway execution logs for the integration receiving the error.6.    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?7.    Use the following CloudWatch Log Insights query to filter the error and select your API Gateway execution log group:fields @timestamp, @message|filter @message like "Execution failed due to a timeout error"|sort @timestamp desc8.    To determine the source of the error, verify that the associated integration endpoint was invoked.9.    Confirm how long the integration took to complete the processing of the request and respond to API Gateway.10.    If the integration wasn’t invoked, implement API retries on the client. (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. The maximum value limits can’t be increased.To reduce your integration's runtimeMake 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 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.

Related informationSetting up REST API integrationsSetting up a WebSocket API integration request in API GatewayConfiguring integrations for HTTP APIsAmazon API Gateway quotas and important notes