# 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:

1. Send it again, same key, same body. You get the order, placed once.
2. If you cannot (your process restarted and lost the key), look it up by its `client_order_id`.
3. If the order shows `unconfirmed`, the trading servers' answer was lost on the way: read it again a second later and it settles.
