Solved Docs

Idempotency

The Idempotency-Key header contract.

Any POST/PATCH that has a side effect and is reachable publicly accepts an Idempotency-Key header — and requires one when the call moves money or credits directly (creating a link, generating a QR, anything billed). Without it on a required endpoint, you get 400 invalid_request.

Idempotency-Key: 8f1c6e2a-9b7d-4e3f-9a21-9c2b7a0f5e41

Use a fresh UUID (or ULID) per distinct action, and reuse the exact same value only when retrying that same action after a timeout, a dropped connection, or a 5xx. What happens on reuse depends on what you send:

You sendYou get
New keyThe action runs
Same key, same request body, action already finishedThe original response again, no second charge (Idempotent-Replayed: true)
Same key, still running409 idempotency_in_progress + Retry-After
Same key, different request body422 idempotency_key_reused — use a new key
Same key, prior attempt failed before it started doing anything (bad auth, validation, insufficient credits, rate limited)The action runs — you're free to retry after fixing the problem

Keys are scoped to your account, held for 24 hours, and the response we replay never includes one-time secrets (a freshly issued API key, a webhook signing secret) — those come back redacted on a replay, by design; if you lost one, issue a new one instead of retrying.

On MCP, this is the idempotency_key parameter — mandatory on every paid write tool, optional on free ones. Composite tools (one call, several underlying steps) use derived keys internally; you still only pass one.

Next: Quickstart: REST · Credits