> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apexiumbet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency - Retrying orders safely with clientOrderId

> How clientOrderId makes order placement safe to retry after a timeout or a dropped connection, and how to read an order whose answer you never received.

A network can drop the answer to a placement after the order was placed. Without a way to retry safely, you would have to choose between missing an order and placing it twice. `clientOrderId` removes that choice.

## The rule

Every order carries a `clientOrderId` that you choose: 1 to 200 characters, unique on your account. Use an identifier from your own system, or a UUID you generate before the first attempt.

| You send | You get |
| - | - |
| A `clientOrderId` never used | The order is placed: `201` |
| The same `clientOrderId` and the same terms | The existing order, unchanged: `200`. Nothing new is placed. |
| The same `clientOrderId` with other terms | `409 CLIENT_ORDER_ID_REUSED`. Nothing new is placed. |

The terms are the selection, the bookmakers, the stake, `minPrice`, `acceptBetterOdds`, `acceptPartialStake` and `expiresAt`. A resent request matches when they are equal; `mode` must be `"place"` both times.

Previews store nothing, so a `clientOrderId` used only in previews is still free.

## Retrying

Retry with the **same body**, never with a new `clientOrderId`:

* **Timeout or dropped connection.** Resend the request. You get the order if it was placed, or it is placed now.
* **`502 UPSTREAM_UNAVAILABLE`.** The bookmaker gateway did not answer, and the order may exist. Resend the request: it returns the order if it was recorded.
* **`409 PREVIOUS_ATTEMPT_UNRESOLVED`.** An earlier attempt with this `clientOrderId` is still being resolved with the bookmaker. Wait a few seconds and resend.
* **`5xx` in general.** Resend with backoff.
* **`4xx` other than the above.** The request itself is wrong: fix it before you send it again.

## Reading an order by your identifier

You can also look the order up without placing anything:

```bash theme={null}
curl https://api.apexiumbet.com/v1/orders/by-client-id/my-order-0002 \
  -H "x-api-key: apx_live_…"
```

It answers `404 NOT_FOUND` when no order was recorded with this identifier.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.