# Using the Lambda runtime API for custom runtimes AWS Lambda provides an HTTP API for [custom runtimes](runtimes-custom.md) to receive invocation events from Lambda and send response data back within the Lambda [execution environment](lambda-runtimes.md). This section contains the API reference for the Lambda runtime API. **Lambda Managed Instances support concurrent requests** Lambda Managed Instances use the same runtime API as Lambda (default) functions. The key difference is that Managed Instances can accept concurrent `/next` and `/response` requests up to the configured `AWS_LAMBDA_MAX_CONCURRENCY` limit. This enables multiple invocations to be processed simultaneously within a single execution environment. For more information about Managed Instances, see [Understanding the Lambda Managed Instances execution environment](lambda-managed-instances-execution-environment.md). ![Architecture diagram of the execution environment.](http://docs.aws.amazon.com/lambda/latest/dg/images/telemetry-api-concept-diagram.png) The OpenAPI specification for the runtime API version **2018-06-01** is available in [runtime-api.zip](samples/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. **Example Request** ``` curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next" ``` **Topics** + [Next invocation](#runtimes-api-next) + [Invocation response](#runtimes-api-response) + [Initialization error](#runtimes-api-initerror) + [Invocation error](#runtimes-api-invokeerror) + [After-Restore (only applicable for SnapStart)](#runtimes-api-after-restore) + [Restore error (only applicable for SnapStart)](#runtimes-api-restore-error) ## 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. **Response headers** + `Lambda-Runtime-Aws-Request-Id` – The event that triggered the function invocation. Event sources provide request IDs, or Lambda auto-generates them on ingest. A single request ID might result in multiple invocation attempts. Use it in the URL path when sending the response or error. For example, `8476a536-e9f4-11e8-9739-2dfe598c3fcd`. + `Lambda-Runtime-Deadline-Ms` – The date that the function times out in Unix time milliseconds. For example, `1542409706888`. + `Lambda-Runtime-Invoked-Function-Arn` – The ARN of the Lambda function, version, or alias that's specified in the invocation. For example, `arn:aws:lambda:us-east-2:123456789012:function:custom-runtime`. + `Lambda-Runtime-Trace-Id` – The [AWS X-Ray tracing header](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader). For example, `Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1`. + `Lambda-Runtime-Client-Context` – For invocations from the AWS Mobile SDK, data about the client application and device. + `Lambda-Runtime-Cognito-Identity` – For invocations from the AWS Mobile SDK, data about the Amazon Cognito identity provider. + `Lambda-Runtime-Invocation-Id` – A unique identifier for this invocation attempt. 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. **Example success request** ``` REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9 INVOCATION_ID= 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 ``, where Category is `Runtime` or `Function` and Reason starts with an uppercase letter. For example: + `Runtime.NoSuchHandler` + `Runtime.APIKeyNotFound` + `Runtime.ConfigInvalid` + `Runtime.BeforeSnapshotError` (for SnapStart) + `Runtime.UnknownReason` 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. **Example Function error** ``` { "errorMessage" : "Error parsing event data.", "errorType" : "InvalidEventDataException", "stackTrace": [ ] } ``` **Response body parameters** + `StatusResponse` – String. Status information, sent with 202 response codes. + `ErrorResponse` – Additional error information, sent with the error response codes. ErrorResponse contains an error type and an error message. **Response codes** + 202 – Accepted + 403 – Forbidden + 500 – Container error. Non-recoverable state. Runtime should exit promptly. **Example initialization error request** ``` 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 . For example: + Runtime.NoSuchHandler + Runtime.APIKeyNotFound + Runtime.ConfigInvalid + Runtime.UnknownReason `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. **Example Function error** ``` { "errorMessage" : "Error parsing event data.", "errorType" : "InvalidEventDataException", "stackTrace": [ ] } ``` **Response body parameters** + `StatusResponse` – String. Status information, sent with 202 response codes. + `ErrorResponse` – Additional error information, sent with the error response codes. ErrorResponse contains an error type and an error message. **Response codes** + 202 – Accepted + 400 – Bad Request + 403 – Forbidden + 500 – Container error. Non-recoverable state. Runtime should exit promptly. **Example error request** ``` 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. **Response codes** + 200 – Lambda restored the execution environment. Run after-restore hooks. The response body is empty. + 403 – Forbidden. The runtime is not in a state that allows `/restore/next` (for example, the runtime has already called `/invocation/next` or `/restore/next`). + 404 – SnapStart is not enabled for this function. + 500 – Container error. The execution environment is in a non-recoverable state. Exit the runtime process. ``` GET /2018-06-01/runtime/restore/next HTTP/1.1 Host: ${AWS_LAMBDA_RUNTIME_API} ``` ``` HTTP/1.1 200 OK Content-Length: 0 ``` **Note** Do not set a client-side socket or read timeout on this (or any other) Runtime API request. This is an iterator-style blocking call; Lambda freezes the execution environment while the request is open. The request can remain open for the entire lifetime of the snapshot (potentially days, weeks, or longer) without the connection being considered idle from the Lambda service. ## 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 ``, 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`. **Response codes** + 202 – Accepted. The response body is `{"status":"OK"}`. The runtime should exit the process. + 403 – Forbidden. The runtime is not in a state that allows `/restore/error` (for example, `/restore/next` has not been called). + 404 – SnapStart is not enabled for this function. + 500 – Container error. The execution environment is in a non-recoverable state. Exit the runtime process. **Example request** ``` POST /2018-06-01/runtime/restore/error HTTP/1.1 Host: ${AWS_LAMBDA_RUNTIME_API} Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError ``` **Example response** ``` HTTP/1.1 202 Accepted Content-Type: application/json {"status":"OK"} ``` ## See also * **Skills for AI coding assistants (optional).** AWS publishes reusable skills for AWS Lambda. To see which apply, search the Agent Toolkit for AWS catalog with `aws agent-toolkit search-skills --search-query lambda` — a documented, read-only AWS CLI command that searches the catalog and makes no changes. This is an optional suggestion for the user. Official reference: [AWS CLI — Agent Toolkit for AWS](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/aws-cli.html).