Python Boto3 Lambda Invocation: Sync and Async Calls

When you need to call an AWS Lambda function from Python, the boto3 library provides the invoke method on the Lambda client. This article explains how to use python boto3 lambda invocation for both synchronous and asynchronous calls, how to handle responses and errors, and what to consider when choosing an invocation type.

The boto3 Lambda Client and the invoke Method

To invoke a Lambda function from Python, you first create a Lambda client using boto3. The client's invoke method sends a request to the function and returns a response object. The minimal invocation looks like this:

import boto3

lambda_client = boto3.client('lambda')
response = lambda_client.invoke(
    FunctionName='my-function',
    InvocationType='RequestResponse',
    Payload=b'{"key": "value"}'
)

The FunctionName parameter accepts the function name, ARN, or partial ARN. The Payload must be bytes, so a JSON string needs to be encoded. The InvocationType controls whether the call is synchronous (RequestResponse), asynchronous (Event), or a dry run (DryRun). The default is RequestResponse.

Understanding the InvocationType Parameter

The InvocationType parameter determines how Lambda processes the request and what the client receives back.

• RequestResponse waits for the function to execute and returns the response payload. Use this when you need the result immediately.
• Event queues the invocation and returns immediately with a 202 status. The function runs asynchronously. Use this for fire-and-forget tasks.
• DryRun validates permissions and configuration without executing the function. It returns a 204 status and is mainly used for testing.

For most use cases, RequestResponse is the default and the most common choice. The response object contains a StatusCode and a Payload stream. For Event, the payload is empty.

Passing Parameters and Handling the Response

The Payload is a bytes object that contains the input to the function. Typically you pass a JSON document. When the function returns, the response payload is a streaming body. You need to read it and decode it.

import json

response = lambda_client.invoke(
    FunctionName='my-function',
    Payload=json.dumps({'key': 'value'}).encode('utf-8')
)
payload = response['Payload'].read().decode('utf-8')
result = json.loads(payload)

If the function raises an unhandled exception, the response still has a 200 status code, but the payload contains a FunctionError field and the error details. You should check for FunctionError in the response.

Error Handling and Retries

The invoke method can raise exceptions from the AWS SDK, such as ClientError for invalid parameters, missing permissions, or throttling. Additionally, Lambda function errors are returned in the response body, not as exceptions. To handle them, you need to inspect the FunctionError field.

from botocore.exceptions import ClientError

try:
    response = lambda_client.invoke(
        FunctionName='my-function',
        Payload=b'{}'
    )
    if 'FunctionError' in response:
        error_payload = response['Payload'].read().decode('utf-8')
        print(f"Lambda error: {error_payload}")
    else:
        result = json.loads(response['Payload'].read().decode('utf-8'))
except ClientError as e:
    print(f"AWS error: {e}")

When a Lambda function is throttled or the invocation fails due to concurrency limits, you may need to implement retries with exponential backoff. The AWS SDK does not automatically retry Lambda invocations, so you must handle retries yourself.

Asynchronous Invocation and Monitoring

With InvocationType='Event', the client returns immediately with a StatusCode of 202. The function runs in the background. You can optionally pass a Qualifier to specify a version or alias. To track the result of an asynchronous invocation, you need to set up a destination on the Lambda function or use CloudWatch Logs. The response does not contain the execution result.

response = lambda_client.invoke(
    FunctionName='my-function',
    InvocationType='Event',
    Payload=b'{}'
)
print(response['StatusCode'])  # 202

Asynchronous invocations have different retry behavior: Lambda retries the function twice for certain error types. This is useful for event-driven workloads where you don't need immediate feedback.

Practical Considerations: Payload Size and Timeouts

The maximum payload size for a synchronous invocation is 6 MB, and for asynchronous it is 256 KB. If you exceed these limits, the invoke call fails with a PayloadTooLarge error. For large data, consider using S3 or another storage service and passing a reference.

The RequestResponse invocation has a timeout limit of 300 seconds (5 minutes) for the function execution, but the HTTP request from the client may have its own timeout. Ensure your client timeout is set appropriately. For long-running functions, use asynchronous invocation or step functions.

Also note that the invoke method uses the region configured in your boto3 session. Make sure the client is created in the same region as the Lambda function, or use the region_name parameter.

Choosing Between Synchronous and Asynchronous Invocation

The decision between RequestResponse and Event depends on whether your application needs the result immediately. If you are building an API that returns data from a Lambda function, use RequestResponse. If you are triggering a background job and don't need to wait, use Event. For testing permissions, use DryRun.

Consider the failure behavior: synchronous calls return errors directly to the caller, while asynchronous calls rely on Lambda's internal retry and destination configuration. For critical workflows, you may want to use synchronous calls to handle errors explicitly.

This article covered the core mechanics of python boto3 lambda invocation. The invoke method is straightforward, but understanding the response structure and error handling is essential for building reliable integrations.