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

The OpenAPI specification for the runtime API version2018-06-01 is available inruntime-api.zip

To create an API request URL, runtimes get the API endpoint from theAWS_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 theGET 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 may be frozen for several seconds.

The request ID tracks the invocation within Lambda. Use it to specify the invocation when you send the response.

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_ID=156cb537-e2d4-11e8-9b34-d36013741fb9curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS"

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 – 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:

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

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:

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

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-d36013741fb9ERROR="{\"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"

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.