Skip to main content
Every authenticated POST on the Experimental API accepts an Idempotency-Key header. When a request with a key succeeds, its response is stored for 24 hours; retrying with the same key replays the stored response instead of executing the request again. This makes it safe to retry a request that timed out or errored on your side without risking a duplicate charge, transfer, or resource. Any unique string up to 255 bytes works as a key — a UUID is a good default. Generate a fresh key for every distinct operation, and reuse that exact key only to retry that operation.
Replayed responses are byte-for-byte identical to the original — including the status code — and carry an Idempotent-Replayed: true header so you can tell a replay apart from a fresh execution.
Error responses are replayed too. If the original request failed with a 4xx, retrying with the same key returns that same error. That failure was the real outcome of the request — send a new key with the corrected request instead.
A few details worth knowing:
  • “Same request” means the method, path, query string, body, and Api-Version-Date all match the original exactly. Any difference is treated as a key reuse and rejected with a 400.
  • Keys are scoped to the authenticated caller. Two different API keys or users can use the same key value without colliding.
  • The header is ignored on unauthenticated requests and on non-POST methods — GET, PATCH, and DELETE requests are naturally safe to retry.
  • If a request fails in a way where the outcome is unknown (for example, a server crash mid-request), retries return a 409 until the key expires — the API never risks executing a request twice.