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

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.