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

# Handling uncertain orders

> What to do when we don't know whether the exchange received an order.

Sometimes we send an order and get no clear answer: the connection drops, or the exchange doesn't reply in time. The order may have arrived, or it may not. We record it as `uncertain` and tell you so. If we treated it as failed and you placed it again, you could buy the shares twice.

## What you see

`POST /v1/orders` returns `201 Created` with `state` set to `uncertain`, and you receive an `order.uncertain` [event](/webhooks). The `reason` field explains the state in words.

We never send an uncertain order again, and nothing is lost: the order stays on your list with its `id`, and it's counted in full against your [daily order value](/limits).

## What to do

1. Don't place the same order again under a new `Idempotency-Key`.
2. Wait for its next event, or retrieve it with `GET /v1/orders/{id}`.
3. Act on the state it moves to:

| New state                               | What it means                         | What to do                                                                |
| --------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
| `pending`, `partially_filled`, `filled` | The exchange has the order.           | Nothing. It continues like any other order.                               |
| `rejected`                              | The exchange didn't accept it.        | Read `reject_reason`.                                                     |
| `refused`                               | It never reached the exchange.        | If you still want the order, place it again with a new `Idempotency-Key`. |
| `cancelled`                             | The exchange had it and cancelled it. | Nothing.                                                                  |

Retrying with the same key is safe while you wait. It returns `200 OK` with the order as it is now.

You can't cancel an uncertain order. A cancel returns `409 order_not_cancelable` until the order's state is known.

## How it resolves

Every 30 seconds we ask the broker about uncertain orders that are more than about a minute old. When the broker holds exactly one open order that matches yours and arrived while we were sending it, we record that it's yours and move it to `pending` or `partially_filled`. Anything we can't match that way, our operators check with the broker and settle by hand: as held, rejected or never received.

## Identical orders while one is uncertain

While an order is uncertain, we refuse an identical order on the same account under a new key: the same `symbol`, `side`, `quantity`, `type`, `time_in_force` and `price_kobo`. You get `409 similar_order_unresolved`, and we store nothing, so your new key stays free. We do this because the broker doesn't echo our reference back, and two identical orders would leave us unable to tell which one it holds.

The error's message names the uncertain order. Retrieve it until it settles:

* If it becomes `pending`, `partially_filled` or `filled`, the exchange has it. Sending your new request would place a second order.
* If it becomes `rejected` or `refused`, send your new request again with the same key.

## Applications and allocations

Applications and allocations can also end in `uncertain`, for the same reasons. We don't send them again, and our operators settle them with the broker.

| Resource    | While uncertain                           | Settles to                                                            |
| ----------- | ----------------------------------------- | --------------------------------------------------------------------- |
| Application | Nothing to do. Retrieve it later.         | `submitted`, then `opened`, or `unplaced` if the broker never had it. |
| Allocation  | Its amount stays reserved in your wallet. | `booked`, or `rejected` with the amount returned to your wallet.      |