Integration Timeout Errors

What this means

An integration timeout occurs when API Gateway sends a request to your backend integration (Lambda function, HTTP endpoint, or AWS service) and does not receive a response within the configured timeout period. In the access logs, timed-out requests show an integrationLatency value of -1 and the client receives a 504 Gateway Timeout response. This is different from a 502 error: a 502 means the backend responded but with something invalid, while a 504 means the backend never responded at all within the allowed time window.

For REST APIs, the maximum configurable integration timeout is 29 seconds. For HTTP APIs, it is 30 seconds. These are hard limits imposed by AWS -- you cannot increase them beyond these values. If your backend legitimately needs more than 29 seconds to process a request, the synchronous API Gateway pattern is the wrong architecture for that workload. The timeout exists because holding an HTTP connection open for extended periods consumes API Gateway capacity, wastes client resources, and provides a poor user experience.

Integration timeouts are problematic because the backend often continues processing after API Gateway has already returned a 504 to the client. For Lambda integrations, the function keeps running until its own timeout (which can be up to 15 minutes). This means the work may actually complete successfully, but the client never knows. You end up with phantom executions that consume compute resources, potentially write to databases, and create data consistency issues because the client assumes the operation failed and may retry it.

Detection criteria

HIGH

Any requests with integrationLatency = -1 detected (more than 0 timeouts).

Example finding

HIGH Integration Timeout Errors

23 requests timed out waiting for backend integration (integrationLatency = -1). All timed-out requests returned HTTP 504 to the client. Affected endpoints: POST /api/reports/generate (18), POST /api/export/csv (5).

Recommendation: Increase integration timeout (max 29s for REST API). Optimize backend processing time. For operations exceeding 29s, switch to asynchronous processing with SQS or Step Functions.

How to fix

Increase the integration timeout to the maximum

If your current integration timeout is set below the maximum, increase it. For REST APIs, set it to 29,000 milliseconds via the Integration Request settings. For HTTP APIs, set the TimeoutInMillis to 30,000 in the integration configuration. This buys your backend more time but does not solve the underlying problem if processing genuinely takes longer. Check this value in your CloudFormation/SAM/CDK template -- it is easy to accidentally deploy with the default of 29 seconds when a lower value was set during development.

Optimize the slow backend operation

Investigate why the backend takes so long. For Lambda, check the function logs for the timed-out invocations. Common causes: unoptimized database queries running sequential full-table scans, waiting for responses from slow third-party APIs without timeouts, processing large files in memory instead of streaming, or DNS resolution delays in VPC-attached Lambdas. Add timeout values to every external HTTP call your Lambda makes (set them to 5-10 seconds shorter than the API Gateway integration timeout to fail gracefully rather than timing out silently).

Switch to asynchronous processing

For operations that legitimately require more than 29 seconds (report generation, large data exports, ML inference), move to an async pattern. Have the API endpoint accept the request, write a job record to DynamoDB, push a message to SQS, and immediately return an HTTP 202 Accepted with a job ID. A separate Lambda (with up to 15-minute timeout) processes the job from the queue. The client polls a status endpoint or receives a webhook notification when the job completes. See our 504 timeout guide for an implementation walkthrough.

Add idempotency to prevent duplicate processing

Since timed-out requests may still complete on the backend, clients will often retry and create duplicate work. Implement idempotency keys: have clients send a unique Idempotency-Key header, and have your backend check DynamoDB for that key before processing. If the key exists, return the cached result instead of re-processing. This prevents duplicate database writes, double charges, and other side effects from timeout-induced retries. The DynamoDB conditional write pattern (attribute_not_exists) makes this atomic and safe under concurrency.

Set Lambda timeout shorter than API Gateway timeout

If your Lambda timeout is longer than the API Gateway integration timeout, Lambda continues running after API Gateway has returned 504 to the client. Set the Lambda timeout to 2-3 seconds less than the API Gateway integration timeout (e.g., 26 seconds for a 29-second integration timeout). This way, Lambda terminates first and returns an error response that API Gateway can relay as a proper 5xx with an error message, rather than a generic 504 with no detail. The Lambda execution time is also wasted compute cost when the response is never delivered.

High Server Error Rate (5xx) — timeouts produce 504 errors that contribute to the 5xx rate
High API Response Latency — high latency often precedes timeouts as the backend approaches the limit

Drop your API Gateway access logs into smplogs to check for this.

Try it free