---
title: "Invoke a function (POST)"
method: POST
path: "/functions/v1/{name}"
tags: ["Functions"]
---

# Invoke a function (POST)

`POST /functions/v1/{name}`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/functions/v1/{name}`
- Auth: API key in header `apikey`

Invokes a deployed function. Free functions return the direct function response. Paid functions require Idempotency-Key for retry-safe billing. A new paid call creates one idempotency record and one durable run, returns the retained result when it finishes within the bounded wait, or returns 202 with run_id/operation_id and next_actions[] for polling. Reusing the same key with the same canonical JSON intent replays the terminal result/error; reusing it with a different intent returns 409 idempotency_conflict. Insufficient allowance and other pre-dispatch failures do not consume the key.

## Path parameters

- `name` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object

## Response `200`

Function response. Schema and content type are controlled by the deployed function.

- unknown

## Other responses

- `202`: Paid invocation accepted and still running. Body carries state: in_progress, run_id, operation_id, Retry-After, and next_actions[] with a poll action; no code (a code names an error, never a state).
- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.
- `403`: Paid invocation was rejected before dispatch, typically insufficient allowance (code ALLOWANCE_INSUFFICIENT — HTTP 403, not 402: this is not an x402 protocol payment challenge, the remedy is topping up the org allowance). The key is released and can be reused after payment with the same request.
- `409`: Idempotency-Key conflict or a replay that cannot return a result. Branch on code: IDEMPOTENCY_KEY_REUSED (the key belongs to a different paid function intent), IDEMPOTENCY_OUTCOME_UNKNOWN (the function may have run; poll the run), IDEMPOTENCY_RESPONSE_EXPIRED (it succeeded but the stored result is gone), IDEMPOTENCY_KEY_EXPIRED (the dedupe window closed). The run's state rides in state; replaying the key returns the same answer (retryable: false), and a new key runs and charges again.
- `413`: Too large to invoke; the function did not run. A body over 1 MB is code VALIDATION_FAILED. A body that, encoded as JSON with the forwarded headers, reaches Lambda's 6 MiB invoke payload is code PAYLOAD_TOO_LARGE, with details.limit (the byte limit) and details.size (the measured bytes).
- `502`: PAID_FUNCTION_FAILED: the paid function ran and failed, on the first call and on every replay of its key. details.function_status is the status the function returned, details.failure the recorded failure; next_actions names the run's logs. retryable: false; a new key runs the function and charges again.

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)