Idempotency

Use idempotency keys to retry mutating REST requests safely, replay completed responses, and avoid executing an operation twice.

Mutating requests may include an idempotency key:

UDX-Idempotency-Key: <unique-key>

The UDX-Idempotency-Key header is optional for mutating requests.

If you omit it, the exchange cannot recognize a retry as a duplicate, so a repeated request executes again. The request still uses normal authentication and member rate limits.

The key is the only replay mechanism. A client ID such as client_order_id, client_rfq_id, or client_quote_id correlates a resource with your own records; it does not replay a response.

The exchange does reject a second order that reuses a client_order_id within the same account and market, so an accidental duplicate order becomes a rejected order, but a repeated RFQ or quote creates a second one. A second account that reuses a client_account_id within your member is rejected with HTTP 409 Conflict. See Asynchronous Writes for how to reconcile a write whose outcome you do not know.

When you need safe retry and replay behavior, use a UUIDv4 or another high-entropy string up to 255 characters. Generate one key for each operation and reuse it only when retrying that operation.

Retry the Same Operation

For a request that included an idempotency key, retry with the same method, path, query string, body, and key. The exchange returns the original response instead of performing the operation again. A replayed response includes:

UDX-Idempotent-Replayed: true

Never reuse an idempotency key for a different request. The exchange rejects that reuse with HTTP 422 Unprocessable Content instead of executing the new operation. If an identical request with the same key is still running, the exchange rejects the duplicate attempt with HTTP 409 Conflict; wait, then retry it with the same key.

When a request includes an idempotency key, the key is part of the signed message, so the signature must include the same key sent in the request. An unkeyed request is signed without that value. See Authentication.

Replay Window

A completed response stays replayable for a bounded time after it completes. Once the window lapses, the exchange forgets the key: a request that reuses it is treated as new and executes again, and a different request under that key is no longer rejected with 422. A repeated account creation with a client_account_id is then rejected with 409 Conflict rather than creating a second account.

Quotes are valid for seconds, so a quote write retried after five minutes cannot duplicate a live quote.

Handle Rejected Requests

The problem’s type distinguishes the two 409 cases: urn:udx:problem:request-with-header-in-progress while the first request is still running, and urn:udx:problem:response-too-large-to-replay when it completed without a replayable response. Do not use detail to choose a recovery path.

A request rejected by a REST rate limit is not saved as the operation’s result. Wait for Retry-After, then, if the mutation used a key, retry with that same key and a new timestamp and signature.