Idempotency-Key header (the X-Idempotency-Key
spelling is accepted as an alias) to retry any write without creating
duplicates.
How it works
- The key is scoped to the API key that sends it + the HTTP method + the request path. Different API keys in your organization never share keys or saved responses. The first request with a given key executes normally and its response is cached for 24 hours.
- A replay (same key, same method, same path and same request body) within 24 hours returns the cached response
with an
Idempotency-Replayed: trueresponse header — the operation is not executed again. - Reusing a key with a different request body returns
409 IDEMPOTENCY_KEY_REUSED, and the request is not executed. Use a fresh key for every distinct operation. The order of JSON fields doesn’t matter. - If a request with the same key is still in flight, the duplicate gets
409 IDEMPOTENCY_KEY_IN_PROGRESSwithstartedAtandstale— back off and retry; you’ll then receive the cached response. Ifstaleis true, the request may have stopped before finishing; see Recovering a stuck key. - 5xx responses are not cached, so retrying after a server error
re-executes the request — that’s what you want. 2xx–4xx responses are
cached; if a request failed validation and you fix the payload, use a
fresh key (reusing the old key with the fixed payload returns
409 IDEMPOTENCY_KEY_REUSED). - Keys are free-form strings up to 255 characters. Use something that
identifies the operation on your side, for example
order-8814-attempt-1.
Scope
This applies to account creation, account PATCH (status,currentBalance,
metadata), rules, plans, lockouts, payouts, team, webhooks — every write on
the platform API. Payouts additionally forward the key to the trade engine
for engine-level double-withdrawal protection.
Recovering a stuck key
If a request dies before its response is saved — client timeout, dropped connection, service disruption — its idempotency key can stay in progress and retries return409 IDEMPOTENCY_KEY_IN_PROGRESS. After 120 seconds in
progress the key becomes stale and can be recovered.
-
Look it up with
GET /platform/v1/organization/idempotency-keys:
The response
stateis one of:completed— the request finished;responseholds the status code and body that a retry would return.in_progress—startedAt,staleandreleasableAtshow when it started, whether it is stale yet, and when it can be released.not_found— the key is free (never sent or expired).
- If completed, use the stored response and don’t resend.
-
If stale, first check directly whether the operation took effect
(for example list the trader’s accounts). Then release the key with
POST /platform/v1/organization/idempotency-keys/release:
Release answers:
200— the key is released; retry with the same key.409 IDEMPOTENCY_KEY_COMPLETED— the request completed;responseholds the stored result. Don’t resend.409 IDEMPOTENCY_KEY_NOT_STALE— the key is not yet stale;releasableAtshows when it can be released.404 IDEMPOTENCY_KEY_NOT_FOUND— nothing on record; the key is free.
- Retry with the same key once released.