Using the Lambda runtime API for custom runtimes

AWS Lambda provides an HTTP API for custom runtimes to receive invocation events from Lambda and send response data back within the Lambda execution environment. This section contains the API reference for the Lambda runtime API.

The OpenAPI specification for the runtime API version 2018-06-01 is available in runtime-api.zip

To create an API request URL, runtimes get the API endpoint from the AWS_LAMBDA_RUNTIME_API environment variable, add the API version, and add the desired resource path.

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

Next invocation

Path – /runtime/invocation/next

Method – GET

The runtime sends this message to Lambda to request an invocation event. The response body contains the payload from the invocation, which is a JSON document that contains event data from the function trigger. The response headers contain additional data about the invocation.

Do not set a timeout on the GET request as the response may be delayed. Between when Lambda bootstraps the runtime and when the runtime has an event to return, the runtime process might be frozen for several seconds.

A request ID (Lambda-Runtime-Aws-Request-Id) identifies a unique event. Request IDs are provided by event sources or auto-generated by Lambda on ingest. Use the request ID in the URL path when sending the response or error.

An invocation ID (Lambda-Runtime-Invocation-Id) represents a single invocation attempt for an event. A single request ID might result in multiple invocation attempts, each with its own unique invocation ID. Lambda uses each invocation ID exactly once and never reuses it. Echo this value back on /response and /error calls. The header is optional for backward compatibility with existing runtimes—omitting it does not trigger a rejection. Lambda only rejects with 400 InvalidInvocationId when the header is present but its value does not match the active invocation.

The tracing header contains the trace ID, parent ID, and sampling decision. If the request is sampled, the request was sampled by Lambda or an upstream service. The runtime should set the _X_AMZN_TRACE_ID with the value of the header. The X-Ray SDK reads this to get the IDs and determine whether to trace the request.

Invocation response

Path – /runtime/invocation/AwsRequestId/response

Method – POST

After the function has run to completion, the runtime sends an invocation response to Lambda. For synchronous invocations, Lambda sends the response to the client.

Request headers

Lambda-Runtime-Invocation-Id – Echo back the value received from /next. Lambda rejects the request with 400 InvalidInvocationId if the value does not match the active invocation.

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
INVOCATION_ID=<value from Lambda-Runtime-Invocation-Id response header>
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS" --header "Lambda-Runtime-Invocation-Id: $INVOCATION_ID"

Initialization error

If the function returns an error or the runtime encounters an error during initialization, the runtime uses this method to report the error to Lambda.

Path – /runtime/init/error

Method – POST

Headers

Lambda-Runtime-Function-Error-Type – The error type that the runtime encountered. This header is optional. Lambda accepts any string value; we recommend using the format <Category.Reason>, where Category is Runtime or Function and Reason starts with an uppercase letter. For example:

Values that do not match this pattern are normalized to Runtime.Unknown or Function.Unknown.

Body parameters

ErrorRequest – Information about the error. Required: no.

This field is a JSON object with the following structure:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Note that Lambda accepts any value for errorType.

The following example shows a Lambda function error message in which the function could not parse the event data provided in the invocation.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" : \"InvalidFunctionException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

Invocation error

If the function returns an error or the runtime encounters an error, the runtime uses this method to report the error to Lambda.

Path – /runtime/invocation/AwsRequestId/error

Method – POST

Headers

Lambda-Runtime-Function-Error-Type – Error type that the runtime encountered. Required: no.

This header consists of a string value. Lambda accepts any string, but we recommend a format of <category.reason>. For example:

Lambda-Runtime-Invocation-Id – Echo back the value received from /next. Lambda rejects the request with 400 InvalidInvocationId if the value does not match the active invocation.

Body parameters

ErrorRequest – Information about the error. Required: no.

This field is a JSON object with the following structure:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Note that Lambda accepts any value for errorType.

The following example shows a Lambda function error message in which the function could not parse the event data provided in the invocation.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" : \"InvalidEventDataException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

After-Restore (only applicable for SnapStart)

Path – /runtime/restore/next

Method – GET

After the pre-snapshot hooks complete, the runtime calls GET /runtime/restore/next. This is an iterator-style blocking call, similar to /runtime/invocation/next, that signals to Lambda that the runtime is ready for the execution environment to be snapshotted. The request blocks until Lambda restores the execution environment from a snapshot, then returns an HTTP 200 response with an empty body.

Headers

No headers required.

Request syntax

GET /2018-06-01/runtime/restore/next HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}

Response syntax

HTTP/1.1 200 OK
Content-Length: 0

Restore error (only applicable for SnapStart)

If an after-restore hook fails or the runtime encounters an error during restore, the runtime uses this method to report the error to Lambda. Lambda fails the in-flight invocation and tears down the execution environment.

Path – /runtime/restore/error

Method – POST

Headers

Lambda-Runtime-Function-Error-Type – The error type that the runtime encountered. This header is optional. Lambda accepts any string value; we recommend using the format <Category.Reason>, where Category is Runtime or Function and Reason starts with an uppercase letter (for example, Runtime.AfterRestoreError). Values that do not match this pattern are normalized to Runtime.Unknown or Function.Unknown.

POST /2018-06-01/runtime/restore/error HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError

HTTP/1.1 202 Accepted
Content-Type: application/json

{"status":"OK"}