Skip to content

One intention, one execution

Give transport retries the same idempotency key.

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. A run that ended FAILED is final: its key keeps replaying that failure, so try again with a new key.

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.

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.

Connect your agent to 3,500+ tools for free

Sign in with Google or GitHub. No card required.