How do I troubleshoot retry and timeout issues when I use an AWS SDK to invoke a Lambda function?

7 minute read

When I invoke my AWS Lambda function with the AWS SDK, the function times out, the API request fails, or API actions get duplicated.

Short description

Retry and timeout issues might occur when invoking a Lambda function with an AWS SDK because of the following conditions:

A remote API is unreachable or takes too long to respond to an API call.
The API call doesn't get a response within the socket timeout.
The API call doesn't get a response within the Lambda function timeout period.
The Lambda functions connected to an Amazon Virtual Private Cloud (Amazon VPC) without valid outbound network routing.
Note: API calls might take longer than expected when network connection issues occur. If your Lambda functions are connected to a VPC, then confirm that it has outbound internet access through a NAT gateway or VPC endpoints. Check for outbound internet access before you update your AWS SDK timeout settings. For more information, see How do I give internet access to a Lambda function that's connected to Amazon VPC?

If you use an AWS SDK to make an API call and the call fails, then the AWS SDK automatically retries the call. SDK-specific settings determine how many times and for how long the AWS SDK retries. To review a table that lists the availability of the retry behavior in each SDK, see Support by AWS SDKs and tools.

To troubleshoot the retry and timeout issues, first review the logs of the API call to find the problem. Then, change the retry count and timeout settings of the AWS SDK. To allow enough time for a response to the API call, add time to the Lambda function timeout setting.

Resolution

Log the API calls made by the AWS SDK

Use Amazon CloudWatch Logs to get details about failed connections and the number of retries for each connection. For more information, see Using CloudWatch Logs with Lambda. Or, see the following instructions for the AWS SDK that you used:

Example error log where the API call failed to establish a connection (connection timeout)

START RequestId: 93f25699-2cbf-4976-8f94-336a0aa98c6f Version: $LATEST
2025-11-01T14:32:27.393Z    93f25699-2cbf-4976-8f94-336a0aa98c6f    INFO    [AWS ec2 undefined 40.29s 3 retries] describeInstances({})
2025-11-01T14:32:27.393Z    93f25699-2cbf-4976-8f94-336a0aa98c6f    ERROR   TimeoutError: Socket timed out without establishing a connection

Example error log where the API call connection was successful, but timed out after the API response took too long (socket timeout)

START RequestId: 405a4537-9226-4216-ac59-64381ec8654a Version: $LATEST
2025-12-08T12:33:18.958Z    405a4537-9226-4216-ac59-64381ec8654a    INFO    [AWS ec2 undefined 30.596s 3 retries] describeInstances({})
2025-12-08T12:33:18.978Z    405a4537-9226-4216-ac59-64381ec8654a    ERROR   TimeoutError: Connection timed out after 30s

Example error log when the Lambda function timeout value is lower than the SDK connection timeout value

REPORT RequestId: 405a4537-9226-4216-ac59-64381ec8654a	Duration: 3003.44 ms	Billed Duration: 3000 ms	Memory Size: 128 MB	Max Memory Used: 74 MB	Status: timeout

Note: Older Lambda log formats show Task timed out after X.XX seconds instead of Status: timeout in the REPORT line.

This error occurs because your Lambda function reached its timeout before the SDK completed the retry cycle. To resolve this issue, see How do I troubleshoot Lambda function invocation timeout errors?

Note: Amazon CloudWatch doesn't create logs if the API request doesn't get a response within your Lambda function's timeout. If the API request ends because of a function timeout, then take one of the following actions:

Change the retry settings in the SDK so that the SDK completes all retries within the timeout.
Increase the Lambda function timeout setting temporarily to allow enough time to generate SDK logs.

Change the AWS SDK's settings

The retry count and timeout settings of the AWS SDK must allow enough time for your API call to get a response. To find the right values for each setting, test different configurations and get the following information:

Average time to get a successful connection
Average time that a full API request takes until successfully returned

For more information on changing retry count and timeout settings, see the following AWS SDK client configuration documentation:

The following example commands change retry count and timeout settings for each runtime.

Note: Be sure to replace the example values for each setting with the values for your scenario.

Example Python (Boto 3) command to change retry count and timeout settings

# max_attempts: retry count / read_timeout: socket timeout / connect_timeout: new connection timeout
from botocore.session import Session
from botocore.config import Config

s = Session()
c = s.create_client('s3', config=Config(connect_timeout=5, read_timeout=60, retries={'max_attempts': 2}))

Example JavaScript V3 command to change retry count and timeout settings

const { S3Client, ListBucketsCommand } = require("@aws-sdk/client-s3");
const { NodeHttpHandler } = require("@smithy/node-http-handler");

const client = new S3Client({
    requestHandler: new NodeHttpHandler({
        connectionTimeout: 30000,
        socketTimeout: 50000
    }),
    maxAttempts: 2
});

Example Java V2 command to change retry count and timeout settings

// apiCallTimeout: total time for the API call including all retries
// apiCallAttemptTimeout: time for a single attempt (retriable)
// connectionTimeout: time to establish a new connection (HTTP client)
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;

S3Client s3 = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(60))
        .apiCallAttemptTimeout(Duration.ofSeconds(30))
        .retryStrategy(r -> r.maxAttempts(3)))
    .httpClientBuilder(ApacheHttpClient.builder()
        .connectionTimeout(Duration.ofSeconds(5)))
    .build();

Example .NET command to change retry count and timeout settings

// MaxErrorRetry: retry count / ReadWriteTimeout: socket timeout / Timeout: new connection timeout
var client = new AmazonS3Client(
    new AmazonS3Config {
        Timeout = TimeSpan.FromSeconds(5),
        ReadWriteTimeout = TimeSpan.FromSeconds(60),
        MaxErrorRetry = 2
});

Example Go V2 command to change retry count and timeout settings

import (
    "context"
    "time"
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/aws/retry"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

// Retry count: wrap the standard retryer with a max attempts value
cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRetryer(func() aws.Retryer {
        return retry.AddWithMaxAttempts(retry.NewStandard(), 3)
    }),
)

client := s3.NewFromConfig(cfg)

// Request timeout: set a per-request deadline with a context
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

output, err := client.GetObject(ctx, &s3.GetObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("my-key"),
})

(Optional) Change your Lambda function's timeout setting

A low Lambda function timeout value might cause healthy connections to drop unexpectedly. Increase the function timeout setting to allow enough time for your API call to get a response.

Use the following formula to estimate the base time needed for the function timeout:

First attempt (connection timeout + socket timeout) + Number of retries x (connection timeout + socket timeout) + 20 seconds additional code runtime margin = Required Lambda function timeout

In a multi-tier architecture, align the timeout at each layer so that each layer allows the layer below it to finish. Use the following order:

SDK timeout (connection + socket + retries)

Lambda function timeout

upstream service timeout (for example, an API Gateway REST API integration timeout, which defaults to 29 seconds)

Note: The API Gateway REST API integration timeout defaults to 29 seconds. For Regional and private REST APIs, request a quota increase to raise this limit. For more information, see Amazon API Gateway quotas.

If you don't align these timeout layers, then requests can fail unpredictably. For example, the upstream service such as API Gateway might return a timeout to the caller before the Lambda function finishes running. Or, the Lambda function might time out before the SDK finishes it's retry cycle.

Example Lambda function timeout calculation

Note: The following calculation is for an AWS SDK that's configured for three retries, a 10-second connection timeout, and a 30-second socket timeout.

First attempt (10 seconds + 30 seconds) + Number of retries [3 * (10 seconds + 30 seconds)] + 20 seconds additional code runtime margin = 180 seconds