Idempotency

An idempotency key identifies one logical execution. Use it whenever a caller might retry after a timeout, connection reset, process restart, or uncertain response.

Send a key

Idempotency-Key: tenant-42-profile-refresh-2026-08-06

Keys may be up to 255 characters. Generate them from a stable operation identity or store a random UUID alongside your application job.

Replay behavior

Reusing a key with the same request resolves to the same logical job. It does not start another execution and does not add another capability charge.

Reusing the key with a different capability or input returns HTTP 409:

{
  "error": {
    "code": "idempotency_conflict",
    "message": "idempotency key has already been used for a different request"
  }
}

Do not recover from a conflict by silently discarding the key. A conflict normally means the caller's operation identity is ambiguous.

Retry pattern

1. Create or load the logical operation's idempotency key.
2. Submit POST /execute with that key.
3. If the transport outcome is unknown, repeat the same request and key.
4. If a job ID was returned, poll that job rather than creating a new operation.

MCP callers should send an operation_key, which works like Idempotency-Key. Without one, MCP derives a short-lived transport key from the authenticated subject, JSON-RPC request ID, and tool arguments: repeating the same call with the same JSON-RPC ID within about 15 minutes replays the original job, and after that the same ID starts a new job. This protects an uncertain transport attempt without letting a later session that reuses small request IDs receive an old result.