Skip to main content
Every mutating endpoint (POST, PUT, PATCH, DELETE) honors idempotency keys uniformly. Send an 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: true response 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_PROGRESS with startedAt and stale — back off and retry; you’ll then receive the cached response. If stale is 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 return 409 IDEMPOTENCY_KEY_IN_PROGRESS. After 120 seconds in progress the key becomes stale and can be recovered.
  1. Look it up with GET /platform/v1/organization/idempotency-keys:
    The response state is one of:
    • completed — the request finished; response holds the status code and body that a retry would return.
    • in_progress — startedAt, stale and releasableAt show when it started, whether it is stale yet, and when it can be released.
    • not_found — the key is free (never sent or expired).
  2. If completed, use the stored response and don’t resend.
  3. 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; response holds the stored result. Don’t resend.
    • 409 IDEMPOTENCY_KEY_NOT_STALE — the key is not yet stale; releasableAt shows when it can be released.
    • 404 IDEMPOTENCY_KEY_NOT_FOUND — nothing on record; the key is free.
  4. Retry with the same key once released.
Stale keys are never released automatically. You can only look up or release keys sent by the same API key (or signed-in member), and you need the permission of the endpoint the key was sent to.