Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

CheckpointDurableExecution

Saves the progress of a durable function execution during runtime. This API is used by the Lambda durable functions SDK to checkpoint completed steps and schedule asynchronous operations. You typically don't need to call this API directly as the SDK handles checkpointing automatically.

Each checkpoint operation consumes the current checkpoint token and returns a new one for the next checkpoint. This ensures that checkpoints are applied in the correct order and prevents duplicate or out-of-order state updates.

Request Syntax


POST /2025-12-01/durable-executions/DurableExecutionArn/checkpoint HTTP/1.1
Content-type: application/json

{
   "CheckpointToken": "string",
   "ClientToken": "string",
   "Updates": [ 
      { 
         "Action": "string",
         "CallbackOptions": { 
            "HeartbeatTimeoutSeconds": number,
            "TimeoutSeconds": number
         },
         "ChainedInvokeOptions": { 
            "FunctionName": "string",
            "TenantId": "string"
         },
         "ContextOptions": { 
            "ReplayChildren": boolean
         },
         "Error": { 
            "ErrorData": "string",
            "ErrorMessage": "string",
            "ErrorType": "string",
            "StackTrace": [ "string" ]
         },
         "Id": "string",
         "Name": "string",
         "ParentId": "string",
         "Payload": "string",
         "StepOptions": { 
            "NextAttemptDelaySeconds": number
         },
         "SubType": "string",
         "Type": "string",
         "WaitOptions": { 
            "WaitSeconds": number
         }
      }
   ]
}

URI Request Parameters

The request uses the following URI parameters.

DurableExecutionArn

The Amazon Resource Name (ARN) of the durable execution.

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: arn:([a-zA-Z0-9-]+):lambda:([a-zA-Z0-9-]+):(\d{12}):function:([a-zA-Z0-9_-]+):(\$LATEST(?:\.PUBLISHED)?|[0-9]+)/durable-execution/([a-zA-Z0-9_-]+)/([a-zA-Z0-9_-]+)

Required: Yes

Request Body

The request accepts the following data in JSON format.

CheckpointToken

A unique token that identifies the current checkpoint state. This token is provided by the Lambda runtime and must be used to ensure checkpoints are applied in the correct order. Each checkpoint operation consumes this token and returns a new one.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: [A-Za-z0-9+/]+={0,2}

Required: Yes

ClientToken

An optional idempotency token to ensure that duplicate checkpoint requests are handled correctly. If provided, Lambda uses this token to detect and handle duplicate requests within a 15-minute window.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [\x21-\x7E]+

Required: No

Updates

An array of state updates to apply during this checkpoint. Each update represents a change to the execution state, such as completing a step, starting a callback, or scheduling a timer. Updates are applied atomically as part of the checkpoint operation.

Type: Array of OperationUpdate objects

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "CheckpointToken": "string",
   "NewExecutionState": { 
      "NextMarker": "string",
      "Operations": [ 
         { 
            "CallbackDetails": { 
               "CallbackId": "string",
               "Error": { 
                  "ErrorData": "string",
                  "ErrorMessage": "string",
                  "ErrorType": "string",
                  "StackTrace": [ "string" ]
               },
               "Result": "string"
            },
            "ChainedInvokeDetails": { 
               "Error": { 
                  "ErrorData": "string",
                  "ErrorMessage": "string",
                  "ErrorType": "string",
                  "StackTrace": [ "string" ]
               },
               "Result": "string"
            },
            "ContextDetails": { 
               "Error": { 
                  "ErrorData": "string",
                  "ErrorMessage": "string",
                  "ErrorType": "string",
                  "StackTrace": [ "string" ]
               },
               "ReplayChildren": boolean,
               "Result": "string"
            },
            "EndTimestamp": number,
            "ExecutionDetails": { 
               "InputPayload": "string"
            },
            "Id": "string",
            "Name": "string",
            "ParentId": "string",
            "StartTimestamp": number,
            "Status": "string",
            "StepDetails": { 
               "Attempt": number,
               "Error": { 
                  "ErrorData": "string",
                  "ErrorMessage": "string",
                  "ErrorType": "string",
                  "StackTrace": [ "string" ]
               },
               "NextAttemptTimestamp": number,
               "Result": "string"
            },
            "SubType": "string",
            "Type": "string",
            "WaitDetails": { 
               "ScheduledEndTimestamp": number
            }
         }
      ]
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

CheckpointToken

A new checkpoint token to use for the next checkpoint operation. This token replaces the one provided in the request and must be used for subsequent checkpoints to maintain proper ordering.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: [A-Za-z0-9+/]+={0,2}

NewExecutionState

Updated execution state information that includes any changes that occurred since the last checkpoint, such as completed callbacks or expired timers. This allows the SDK to update its internal state during replay.

Type: CheckpointUpdatedExecutionState object

Errors

For information about the errors that are common to all actions, see Common Errors.

InvalidParameterValueException

One of the parameters in the request is not valid.

message: The exception message.
Type: The exception type.

HTTP Status Code: 400

ServiceException

The AWS Lambda service encountered an internal error.

HTTP Status Code: 500

TooManyRequestsException

The request throughput limit was exceeded. For more information, see Lambda quotas.

retryAfterSeconds: The number of seconds the caller should wait before retrying.

HTTP Status Code: 429