Lambda Function Times Out Before API Gateway Integration Completes: Diagnosing Mismatched Timeout Settings

Question

Goal: Configure an AWS Lambda function invoked synchronously through Amazon API Gateway so that the function completes before the integration timeout, thereby avoiding 504 Gateway Timeout errors while keeping compute waste low.
Constraints: The Lambda runtime enforces a hard timeout at the configured value, issuing a SIGTERM that allows a brief cleanup window before forced termination; API Gateway applies its own integration timeout that can cancel the request independently of the function’s execution. The function must perform any side‑effects idempotently because client cancellation does not stop the Lambda runtime.
Uncertainty: Determining the optimal Lambda timeout relative to the API Gateway timeout, accounting for the SIGTERM window, and balancing the risk of premature termination against wasted compute on timed‑out invocations.
What Lambda timeout value should be set relative to the API Gateway integration timeout to prevent 504 errors? How large should the SIGTERM cleanup window be compared to the function timeout to allow graceful shutdown? What trade‑offs arise when lowering the Lambda timeout to reduce wasted compute versus increasing the chance of incomplete work?

Tasadduq Burney · Answer

The Optimal Timeout Configuration
To prevent 504 Gateway Timeout errors, set the AWS Lambda function timeout to be shorter than the API Gateway integration timeout. Specifically, the Lambda timeout should be the API Gateway timeout minus the SIGTERM cleanup window (up to 3 seconds) and a small safety buffer (approximately 0.5 to 1 second).

Example Calculation:
If your API Gateway integration timeout is set to 29 seconds (the maximum for REST APIs), configure your Lambda timeout to 25–26 seconds. This ensures the function is terminated and can attempt a graceful shutdown before API Gateway closes the connection and returns a 504 error to the client.

Execution Behavior and the SIGTERM Window
It is important to distinguish between the integration timeout and the runtime termination process:

API Gateway Timeout: This is a hard limit on how long the gateway will wait for a response. If this limit is reached, the client receives a 504 error immediately, regardless of whether the Lambda function is still running.
Lambda Timeout & SIGTERM: When a Lambda function reaches its configured timeout, the runtime sends a SIGTERM signal to the process. The runtime then allows a window of up to 3 seconds for the process to perform cleanup before issuing a SIGKILL to force termination.

Trade-offs in Timeout Tuning

Strategy
Benefit
Risk

Lower Lambda Timeout
Reduces wasted compute costs on requests that would have timed out at the gateway anyway.
Higher probability of incomplete work or premature termination of valid long-running requests.

Higher Lambda Timeout
Increases the chance of completing complex tasks.
Increases cost for failed requests and leads to 504 errors if the timeout exceeds the API Gateway limit.

Verification Steps
To verify your configuration, use a controlled test environment with the following steps:

Deploy a test Lambda function that uses a sleep command for a duration slightly above and below your configured timeout.
Invoke the function via API Gateway and monitor the HTTP response code.
Check CloudWatch Logs for the function. Look for reports indicating the process was terminated or timed out.
Verify that the Duration reported in the logs is consistently lower than the API Gateway integration timeout.

Note on Idempotency: Because API Gateway cancellation does not stop the Lambda runtime, any side effects (database writes, API calls) must be idempotent to prevent duplicate data if a client retries a request that actually completed after the 504 was issued.

Diagnostic Detail Required: Are you using a REST API or an HTTP API? (HTTP APIs have different default timeout behaviors and limits compared to REST APIs).

Lambda Function Times Out Before API Gateway Integration Completes: Diagnosing Mismatched Timeout Settings

1 answer

The Optimal Timeout Configuration

Execution Behavior and the SIGTERM Window

Trade-offs in Timeout Tuning

Verification Steps

Your perspective belongs here.

0 question comments

Strategy	Benefit	Risk
Lower Lambda Timeout	Reduces wasted compute costs on requests that would have timed out at the gateway anyway.	Higher probability of incomplete work or premature termination of valid long-running requests.
Higher Lambda Timeout	Increases the chance of completing complex tasks.	Increases cost for failed requests and leads to 504 errors if the timeout exceeds the API Gateway limit.