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.
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 send | You get |
|---|---|
| New key | The action runs |
| Same key, same request body, action already finished | The original response again, no second charge (Idempotent-Replayed: true) |
| Same key, still running | 409 idempotency_in_progress + Retry-After |
| Same key, different request body | 422 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