# One intention, one execution.

Give transport retries the same idempotency key.

Updated: 2026-09-21.
## Create a key before dispatch

For REST, send `Idempotency-Key` on `POST /v1/run`. For MCP, supply `idempotency_key` to `run_tool`. Generate a non-secret unique value for each new intended execution and retain it with the tool, input and run ID.

## Reuse it only for the same request

If the connection fails or a retryable response leaves the outcome uncertain, retry the same tool and identical input with the same key and credential. The service can replay the existing execution instead of dispatching a second one. A changed request with a reused key can produce a conflict; inspect the original execution and use a new key only for a genuinely new intention.

## Avoid accidental duplicate spend

Calling the same tool twice with the same input but no idempotency key can start two billable executions. Repeated calls with new keys are separate executions. Do not retry a pending result as a new run. Follow [asynchronous executions](/docs/async).

Idempotency does not make every provider action reversible, grant permissions or guarantee a provider result. Keep retries bounded and stop on a permission, input or spending error.

---

[HTML page](/docs/idempotency) · [Agent index](/llms.txt)