Returning a response before api gateway timeout

[Chaz6]

I have a lambda behind an api gateway, which has an integration request timeout of 29000ms. The lambda uses idempotency so that subsequent requests received the cached response once the request has been processed. The lambda can take more than 29 seconds to complete, so I would like to be able to signal to the client that the request is still being proceessed before the api gateway sends a request timeout error.

[Yuno15-bb]

A single synchronous invocation can't send an early "still processing" and then keep working. With the Lambda proxy integration, the response is the handler's return value, and once the handler returns, the invocation is over. When API Gateway gives up at 29 s, it just returns a 504 to the client. The function keeps running until it finishes or hits its own timeout.

Idempotency lets you take advantage of that: retries of the same request can get a 202 while the first invocation is still running, then the cached result once it's done.

1. Return 202 to retries while the first invocation is running

When a second request arrives with the same payload before the first one has finished, Powertools raises IdempotencyAlreadyInProgressError (docs). If you use @idempotent on the handler, that exception leaves the handler and API Gateway turns it into a 502. Put the idempotency on the work function instead, and catch the exception in the handler:

import json

from aws_lambda_powertools.utilities.idempotency import (
    DynamoDBPersistenceLayer,
    IdempotencyConfig,
    idempotent_function,
)
from aws_lambda_powertools.utilities.idempotency.exceptions import (
    IdempotencyAlreadyInProgressError,
)

persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
config = IdempotencyConfig()


@idempotent_function(data_keyword_argument="order", config=config, persistence_store=persistence_layer)
def process_order(order: dict) -> dict:
    ...  # the long-running work
    return {"order_id": order["order_id"], "status": "done"}


def lambda_handler(event, context):
    # Lets the in-progress lock expire if this invocation times out.
    config.register_lambda_context(context)
    order = json.loads(event["body"])

    try:
        result = process_order(order=order)
    except IdempotencyAlreadyInProgressError:
        # Same payload, first invocation still running.
        return {
            "statusCode": 202,
            "headers": {"Retry-After": "10"},
            "body": json.dumps({"status": "processing"}),
        }

    return {"statusCode": 200, "body": json.dumps(result)}

I ran this with Powertools 3.35.0 against a mocked DynamoDB table (moto). The first call worked for 3 s, a second call with the same body 1 s later got 202 {"status": "processing"}, and a third call after the first finished got 200 with the cached result. The work ran once. Without the try/except, the second call raised IdempotencyAlreadyInProgressError instead.

Two things to keep in mind:

• The retry must produce the same idempotency key. By default that's the whole order dict. If the body can differ between retries (timestamps, request IDs), use IdempotencyConfig(event_key_jmespath="order_id") (payload subset).
• register_lambda_context matters here (Lambda timeouts). Without it, if the first invocation dies from a timeout, retries keep getting 202 until the whole idempotency record expires.

The limit of this approach is that the first caller still gets the 504. Clients have to treat a 504 on this endpoint as "retry later".

2. If the first response has to arrive before 29 s

Then the work can't stay in the synchronous invocation. The options I know of:

• Asynchronous job + polling. Return 202 right away and hand the work to an asynchronous invocation, SQS or Step Functions. The client then polls a status endpoint. AWS documents this pattern in Process events asynchronously with API Gateway and Lambda. With a non-proxy integration, API Gateway can also invoke the function asynchronously itself with the X-Amz-Invocation-Type: 'Event' header (docs). Keep the idempotency on the worker.
• Raise the integration timeout. For Regional and private REST APIs (not edge-optimized), the 29 s limit is a quota you can ask to raise. AWS notes that this "might require a reduction in your Region-level throttle quota" (quotas). This only helps if the job reliably finishes within the new limit.
• Response streaming. REST APIs can stream a Lambda proxy response with a timeout of up to 15 minutes (docs). Lambda only streams natively on Node.js, though. For Python you need a custom runtime or the Lambda Web Adapter (docs).

I tested option 1 locally only, not behind a real API Gateway. The options in part 2 come from the AWS docs linked above, not from a test.