Idempotency

A request can time out after we’ve acted on it. If you send it again, you need to know it won’t place a second order. An Idempotency-Key gives you that: we tie the key to the first request, and every retry with the same key returns that first result.

​

Which requests need a key

​

Choose a key

• Generate one key for each order, application or allocation, such as a UUID.
• Save it with your own record before you send the request, so a crash on your side can’t lose it.
• Send the same key on every retry of that request.
• Use 1 to 255 printable ASCII characters, with no spaces. We compare keys byte for byte.
• Send the header once. Two Idempotency-Key headers return 400 invalid_request.

Keys never expire, and each key belongs to one request for good. Your keys are separate from other partners’ keys.

​

What a retry returns

For an order, we compare account, symbol, side, quantity, type, time_in_force and price_kobo after we read them, so a retry with different spacing or field order is still the same request. Account codes and symbols are compared without regard to letter case. For an allocation we compare account and amount_kobo, and for an application every field. A retry returns the first result even when the result was a refusal. A retried order that was rejected returns 422 order_rejected again, and one that was never sent returns 503 order_not_sent again. Applications and allocations work the same way. We look up the key before we check the account or contact the broker, so a retry gets its answer even when the broker can’t be reached.

​

When to use a new key

Whether you can reuse a key depends on whether we stored the request.