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

# Errors

> Every error is application/json with the same one-field shape, on every route.

Every error is `application/json` with the same one-field shape, on every route:

```json theme={null}
{ "error": "clientOrderId required" }
```

The message is written for a human reading a log. Show it, log it, or match on the status code.
There is no separate error-code enum to memorize.

| Status | Meaning                                                                                                                                                                                                                                                                                                                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Malformed input: an unparseable timeframe, an unknown `broker`/`account` selector, an invalid cursor. Always fails closed; never a silent fallback to a default.                                                                                                                                                                                                                                 |
| `401`  | No credential resolved: the key is absent, malformed or revoked, and the origin is not allowlisted.                                                                                                                                                                                                                                                                                              |
| `402`  | Challenges only: the program has a non-zero `priceCents` and this engine collects no fee.                                                                                                                                                                                                                                                                                                        |
| `403`  | `origin not allowed`: the CSRF gate in front of the trading and account routes, not an authorization verdict.                                                                                                                                                                                                                                                                                    |
| `404`  | On `/api/market/symbol-info`, an unknown symbol. On Challenges, also the honest answer when `CHALLENGES_ENABLED` is off.                                                                                                                                                                                                                                                                         |
| `409`  | The `clientOrderId` was already used and the earlier order stands; a saved exit plan was edited since the preview (`exit_plan_conflict`); the position changed under a close (`position_changed`). On Challenges enrollment, an attempt is already in flight.                                                                                                                                    |
| `423`  | The account is risk-locked and new exposure is refused until the lock lifts.                                                                                                                                                                                                                                                                                                                     |
| `429`  | Rate limited. Honor `Retry-After`.                                                                                                                                                                                                                                                                                                                                                               |
| `502`  | A venue read failed part-way through building an account snapshot. Nothing partial is ever served: a half-read account cannot be told apart from a complete picture of an emptier one. Re-read.                                                                                                                                                                                                  |
| `503`  | On the money routes, try again: the account is served by another engine machine, the engine is draining, the account could not be identified this second, or an earlier command on this account has an outcome the engine has not yet confirmed. Every such answer carries `Retry-After`. Elsewhere, an upstream feed is unconfigured or down, or a futures feed is refused with a typed reason. |

Three of these deserve special handling in your client:

* **`409` means stop, not retry.** Your intent already landed. Re-sending with the same
  `clientOrderId` will keep answering `409`, and re-sending with a new one would place a second
  order. Read the account stream to see what actually rests.
* **`503` on a money route means the command was not run.** Nothing reached the venue, so the same
  `clientOrderId` may be sent again after `Retry-After`. The one exception is the unknown-outcome
  answer: an earlier command with that id may be resting at the venue, so read the account stream
  before deciding, and never mint a new id to get past it.
* **`423` means the account is locked, not that the request was wrong.** Surface it to the trader
  as a risk lock. Retrying in a loop just re-earns the same refusal.
* **`429` tells you exactly how long to wait.** Honor `Retry-After` rather than retrying tightly.

One rule that surprises people: a present `Origin` header must be on the allowlist even when a
valid key is attached. A bearer excuses a missing Origin, never an untrusted one.