Working with the API
Idempotency.
Why a lost answer never places a second order: the Idempotency-Key, what a retry gets back, and your own order ids.
A connection can drop after your order reached us and before the answer reached you. Did the order go through? With an Idempotency-Key, you never have to guess: send the same call again with the same key, and you get the first call's result instead of a second order.
Where it is required#
Every call that creates something or acts on the market takes an Idempotency-Key header, and is refused with idempotency_key_required without one:
| Call | |
|---|---|
POST /v1/accounts/{account_id}/orders | Place an order |
POST /v1/accounts/{account_id}/orders/cancel-all | Cancel every order |
POST /v1/accounts/{account_id}/positions/{market}/close | Close a position |
POST /v1/accounts/{account_id}/flatten | Close everything |
POST /v1/accounts/{account_id}/strategies | Start a strategy |
POST /v1/accounts | Open a sandbox account |
PUT and DELETE calls say what the end state should be, never what to add, so sending one twice changes nothing: they need no key. A change of an order (PATCH .../orders/{order_id}) takes a key when you give one: the same change sent again under it is done once. Without a key, a change is sent once and never again by the SDKs (a size changed again after a partial fill would not be the same change).
The key is any string of 1 to 128 printable characters that you never reuse for another call: a UUID is ideal. The SDKs make one for every such call and keep it across their own retries.
What a retry gets#
The key is remembered for 24 hours, for your API key and that call: the account and the market in its path are part of it. The same key on another account or market is another call, and it is done.
| You send | You get |
|---|---|
| The same key and the same body | The first call's result, with Idempotent-Replayed: true. For an order, the order as it is now (filled since, for example) |
| The same key while the first call is still running | 409 operation_in_progress with Retry-After: 1: ask again in a second |
| The same key with a different body | 400 idempotency_key_reused: nothing is done |
A refusal for good counts as a result when the order reached the trading servers: the retry gets the same refusal, with the same order_id. A refusal that says retryable: true (the account not ready yet, no price, the engine busy) is no result: send the call again with the same key and the same client_order_id and it is done again (the refused attempt stays readable under its own order_id). A call refused before the trading servers (a field missing, a size off the step) keeps nothing, so you can fix it and send it again with the same key.
Your own order ids#
Give an order your own client_order_id (1 to 64 characters: letters, digits, ., _, : and -) and you can find it again from anywhere, even from another process or with another key: GET /v1/accounts/{account_id}/orders?client_order_id=momentum-0142. It is unique across your accounts in its environment: a second order with the same client_order_id is refused with client_order_id_conflict, the first one named in order_id. Strategies take a client_strategy_id the same way (the programs: oco, twap, vwap, scaled, chase). A program whose orders are refused when it starts made nothing: the error answers, and its client_strategy_id is free to use again.
A recovery that always works#
When a call that places an order fails without an answer:
- Send it again, same key, same body. You get the order, placed once.
- If you cannot (your process restarted and lost the key), look it up by its
client_order_id. - If the order shows
unconfirmed, the trading servers' answer was lost on the way: read it again a second later and it settles.