Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Boto3 Lambda Invocation: Sync and Async Calls

Learn how to invoke AWS Lambda functions from Python using boto3. Covers synchronous and asynchronous calls, payload handling, error handling, and choosing an invocation type.

~4 min readPython
#boto3#AWS Lambda#invocation#Python SDK
Diagram of a Python script using boto3 to invoke an AWS Lambda function with both synchronous and asynchronous request paths.

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 invoke Lambda functions with boto3 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, 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:

python
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.

python
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, a synchronous invoke response still has a 200 status code, but the response includes a FunctionError field and the error details. For synchronous calls, 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. Lambda function errors, however, are returned in the response body rather than raised as exceptions. Handle them by inspecting the FunctionError field.

python
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}")

If the function runs and returns a FunctionError, boto3 will not retry it. For workflows that must tolerate throttling or transient failures, add your own retry logic with backoff. Also consider whether retrying an invocation is safe in your application, because a retried function may run more than once.

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, configure a destination on the function or use CloudWatch Logs. The invocation response does not contain the execution result.

python
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 makes Event useful for event-driven workloads where immediate feedback is not needed.

Practical Considerations: Payload Size and Timeouts

The maximum payload size for a synchronous invocation is 6 MB, and for an asynchronous invocation it is 256 KB. If you exceed these limits, the AWS API rejects the invocation. For large data, consider using S3 or another storage service and passing a reference to the data.

Lambda functions have a configurable timeout, with a maximum of 15 minutes. For synchronous calls, make sure the client's HTTP timeout is longer than the function timeout so the client can receive the result. For long-running tasks, consider asynchronous invocation or AWS 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 do not need to wait, use Event. For testing permissions, use DryRun.

Consider the failure behavior: synchronous calls return Lambda function errors in the response so the caller can handle them explicitly, while asynchronous calls rely on Lambda's built-in retries and destination configuration. For critical workflows, synchronous calls give you more direct control.

This article covered the core mechanics of invoking Lambda functions with boto3. The invoke method is straightforward, but understanding the response structure and error handling is essential for building reliable integrations.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.