---
cuppy_hub: aws
cuppy_path: reference/lambda/invoke.md
cuppy_section: docs
cuppy_doc: Q7D6-1W8S
cuppy_doc_uuid: 0210ba4b-f63a-4dd6-8b71-e71888453d39
cuppy_permalink: https://cuppy.io/aws/d/Q7D6-1W8S
cuppy_version: 4
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/aws/docs/reference/lambda/invoke
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: 49f192d12d468ee5000880b8ce051804ad77ac8d27fdc4361243a212a9729362
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Invoke

**`Invoke` runs a function synchronously (`RequestResponse`, the default) or queues it (`Event`).** A synchronous call returns HTTP 200 **even when the function failed**. Success means a 200 with no `FunctionError`.

## The request

### CLI (v2)

```
aws lambda invoke --function-name <name|ARN|name:alias> \
  --cli-binary-format raw-in-base64-out \
  --payload '{"hello":"world"}' \
  --log-type Tail \
  out.json
```

- `out.json` (positional, required) receives the function's response body.
- `--cli-binary-format raw-in-base64-out` lets you pass plain JSON. Without it, CLI v2 expects base64 (UNVERIFIED in the collected sources; this is CLI behaviour, not part of the API).
- `--invocation-type Event` queues the event. `DryRun` checks permissions and parameters without running anything.
- `--qualifier <version|alias>` targets a specific version.

The command prints `StatusCode`, `ExecutedVersion`, and, when the function failed, `FunctionError`.

### TypeScript, AWS SDK for JavaScript v3

```ts
import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";

const lambda = new LambdaClient({ region: "<region>" });

const res = await lambda.send(new InvokeCommand({
  FunctionName: "<function name, ARN, or name:alias>",
  InvocationType: "RequestResponse", // or "Event" (async) or "DryRun"
  Payload: new TextEncoder().encode(JSON.stringify({ hello: "world" })),
  LogType: "Tail",                   // last 4 KB of the log, base64, sync only
}));

const body = res.Payload ? new TextDecoder().decode(res.Payload) : "";
if (res.FunctionError) {
  // HTTP 200 but the function threw: body is {"errorType", "errorMessage", "trace"}
  throw new Error(`function error (${res.FunctionError}): ${body}`);
}
console.log(res.StatusCode, body);
if (res.LogResult) console.log(Buffer.from(res.LogResult, "base64").toString("utf8"));
```

`Payload` is bytes in both directions. Service errors (throttling, not found, too large) are thrown by `send()` as exceptions named after the error, such as `TooManyRequestsException`. Catch them separately from function errors.

## What it returns

| Invocation type | Success status | Body |
|---|---|---|
| `RequestResponse` | 200 | The function's return value (JSON), or an error object when `FunctionError` is set |
| `Event` | 202 | Empty; the event is queued |
| `DryRun` | 204 | Empty |

`LogType: Tail` adds `LogResult`: the **last 4 KB** of the invocation's log, base64-encoded. It is for synchronous calls only. Full logs are in CloudWatch Logs under `/aws/lambda/<function>`.

## Permissions

- The caller needs `lambda:InvokeFunction` on the function ARN. Calling a version or alias needs that qualified ARN, or a `:*` suffix in the policy resource.
- Cross-account callers and AWS services additionally need the **function's resource-based policy** to allow them (`reference/lambda/permissions.md`).
- The function's own actions use its **execution role**, never the caller's credentials.

## What it changes

- **Runs your code**, with whatever side effects the code has. A `DryRun` does not.
- **Synchronous:** no automatic retry by Lambda. The caller decides; the SDK's own retry policy retries only throttles and service errors (UNVERIFIED SDK retry details).
- **Asynchronous:** Lambda retries a failed invocation **up to two more times**, so the same event can run three times. Make handlers idempotent. Configure an on-failure destination or a dead-letter queue to catch final failures.
- **Cost:** each invocation, including one that errors, is a billed request, plus compute time (GB-seconds). Retries of async events are new invocations. Throttled requests aren't counted as invocations. See `reference/cloudwatch/metrics-and-math.md` and `patterns/alternatives/choosing-compute.md`; no prices here.
- **Concurrency:** each in-flight synchronous call holds one execution environment; bursts throttle with `TooManyRequestsException` (429).

## Limits

- Payload: 6 MB request and response (synchronous), 1 MB (asynchronous), 200 MB for a streamed response.
- The invocation stops at the function's timeout (at most 900 s). A client-side read timeout shorter than that abandons the call, but the function keeps running.

## Failures

`TooManyRequestsException`, `ResourceNotFoundException`, `RequestTooLargeException`, `ResourceConflictException`, `RecursiveInvocationException`, `KMS*` and `ENI`/`Subnet` 502s: see `reference/lambda/errors.md`.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->