Skip to main content
Seven endpoints require an Idempotency-Key header. Replaying a key returns the original result instead of creating a second resource.

​
Using a key

  1. Generate a UUID before the first attempt and store it with your record of the operation. A UUID is accepted by every endpoint below.
  2. Reuse that key and the same request body when retrying the operation. Send requests with the same key one at a time.
  3. Use a new key for a new operation. Keys never expire.
The header is not part of the signature string. Generate a fresh nonce, timestamp, and signature for every attempt; see Authentication. Where a UUID is required, use the hyphenated 8-4-4-4-12 form. Uppercase and lowercase hex digits are both accepted, but keys are compared as strings: changing the case creates a different key. Preserve the exact value on retries.

​
Endpoints that require a key

​
Replays and conflicts

Create Account does not compare the body: a replayed key returns the original account whatever the body. Create Virtual Account compares only the group and currency. Changing either returns 409 IDEMPOTENCY_CONFLICT; changing only label returns the original virtual account and ignores the new label. Create Payout, Create Transfer, and Simulate Payin reject a different request payload with 409 IDEMPOTENCY_CONFLICT. Submit Agreement Actions and Upload Document use 409 BUSINESS_RULE_VIOLATION for a conflicting payload. For Create Payout, payment_rail is part of the compared request: changing it under the same key returns 409. An existing payout created without payment_rail can still be replayed with that field omitted or set to null; a new VA payout requires a non-null payment_rail. Older payouts created before payload comparison was introduced may return the original payout without checking for a mismatch. A trading-account payout rejected for INSUFFICIENT_FUNDS or CREDIT_LIMIT_EXCEEDED is persisted as failed. The first response is 422 with error.details.payout_id; replaying the same key and body returns 200 with that failed payout. Always inspect status. After resolving the funding issue, use a new key to create a new payout.

​
Endpoints without a key

Create Virtual Account Group takes no header: a repeat for the same account and group type returns the existing group with 200. Other create endpoints do not use this header to replay a previous result. Before retrying, check whether the resource was created; a repeat may create a duplicate or hit an endpoint-specific uniqueness rule. See Failure and recovery for recovery by operation.