Orders, idempotency, and retries

Order flow

The normal flow for one order is:

1. Send POST /trading/accounts/{account_id}/orders with a new Idempotency-Key and client_order_id.
2. Read the 201 response. It confirms command acceptance and contains the platform-generated order_id and the supplied client_order_id. It does not mean the order is resting or filled.
3. Receive order_update frames from /orders. Each frame contains the full order view, including status, filled_qty, and status_reason.
4. Treat FILLED, CANCELLED, EXPIRED, and REJECTED as terminal states.

Request-body rules:

• token is required. BUY NO executes as SELL YES, and SELL NO executes as BUY YES; the matching engine uses one book of YES contracts.
• Keep client_order_id unique among active orders. Reusing old values makes client-ID targeting ambiguous, so the safest policy is never to reuse them. An amend does not change the ID.
• Amend and cancel identify an order by order_id or client_order_id and require market_id in the body. Prefer order_id.
• Changing price or increasing quantity loses queue priority. Decreasing quantity at the same price preserves it.
• A command can be accepted by REST and later rejected by the engine. Rejected amend and cancel commands arrive as order_reject frames.
• DELETE /trading/markets/{market_id}/orders cancels the broker's resting orders on that market across all accounts. It returns ref_id; each resulting cancellation has the same value in last_cmd_id_hex.

Idempotency and retries

Every state-changing POST, PATCH, and DELETE requires an Idempotency-Key.

1. Generate a key for each logical command.
2. Persist the key and exact request before sending it.
3. On a timeout or retryable 5xx, resend the same request with the same key.
4. Never reuse the key with different content.

Interpret success codes according to the operation contract:

• 200 or 201 normally means first acceptance for order commands.
• 202 means an idempotent replay for order commands, but it is also the normal first-acceptance response for POST .../merge. Do not infer replay from the status code alone.
• A successful command response confirms acceptance, not final execution.

Important errors:

• 400, 404, or 422: the request, identifier, or current resource state is invalid for that operation. Fix or reconcile before retrying.
• 403: the broker is not permitted to perform the operation.
• 409 idempotency_key_mismatch: the key was reused with different content. This is a client bug; do not retry.
• 429: wait for Retry-After. Repeating an already recorded command with the same key and content does not consume command quota.
• 503 outcome_unknown: the safe retry period has passed. Stop retrying the command and reconcile its resource state.
• Other retryable 5xx: use bounded backoff and preserve the same key and request bytes.

Idempotency context has a sliding TTL of one hour from the latest request carrying that key. Every repeat refreshes the TTL, including a payload mismatch. Do not treat expiration as permission to submit the logical command again.