# Reason codes

> Every code reTrade can give, what happened, and what the agent can do next.

Status: In development. Not released yet; names and formats may change. Web page: https://retrade.app/docs/reference/reason-codes

## reTrade’s reason codes

A CUT or BLOCK names the rule that decided it in `deciding`, as `{"code": …}`, or `{"code": "approval_line", "reason": …}` for a dollar line. An ALLOW has none.

Every reason code reTrade can give:

| Code | What happened | What the agent can do |
|---|---|---|
| `ACCOUNT-UNKNOWN` | The account isn’t registered, or its household doesn’t resolve. | Ask its user to register the account. |
| `STOPPED` | A stop is engaged for the tenant, the account or the agent. | Wait for an admin to release it. |
| `AGENT-STOPPED` | The runaway check switched this agent off. | Ask its user to have an admin re-enable it. |
| `runaway_throttle` | Too many orders a minute, or a duplicate. | Slow down; don’t repeat the order. |
| `INVALID-ORDER`, `UNSUPPORTED`, `SYMBOL-UNKNOWN`, `INTENT-MISMATCH` | The order is malformed, of a kind reTrade doesn’t support, for an unknown listing, or mislabelled. | Fix the order. |
| `QUOTE-MISSING`, `QUOTE-STALE`, `QUOTE-INVALID`, `STATE-MISSING`, `STATE-INCOMPLETE`, `STATE-STALE`, `STATE-INCONSISTENT`, `FX-MISSING`, `FX-STALE`, `FX-INVALID` | The quote, the account data or the exchange rate is missing, old or doesn’t add up. | Retry with fresh broker data. |
| `PRICE-MOVE`, `PRICE-COLLAR`, `MARK-MISMATCH` | A price moved too far, the limit is too far from the last price, or the account’s mark doesn’t match the quote. | Check prices and the limit. |
| `STATE-JUMP` | The account’s value jumped since its last accepted data. | Declare deposits and other changes, or have an admin confirm the data. |
| `HOUSEHOLD-STALE` | A household limit needs fresh data from the household’s other accounts. | Send fresh data for those accounts. |
| `agent_permission`, `order_form`, `restricted_list`, `new_position_pace`, `written_exit` | A rule forbids this order. | Re-plan. |
| `single_name_cap`, `group_cap`, `order_size_cap`, `cash_funding`, `no_short` | A limit leaves room for fewer shares: CUT, or BLOCK when there’s no room. | Accept the cut, or re-plan. |
| `AG-RESERVED` | Orders still working use up the room for now. | Retry once those orders show at the broker. |
| `approval_line` with `per_order`, `per_agent_day`, `per_day`, `openings_pct` or `hard_cap_day` | The order is over one of the account’s dollar lines. `fits` is set. | Resize to `fits` and send it again, or ask its user. |
| `agent_conflict` | Another agent is trading the same stock the other way. `fits` is 0. | Re-plan with the other agent’s order in mind, or ask its user. |
| `REF-DISAGREE` | reTrade’s two independent checkers disagreed. | Nothing; reTrade’s staff are alerted. |

## The SDK’s own reasons

When the SDK acts without an answer, or doesn’t place an approved one, it says why in the result’s `reason`, never in `deciding`.

Reasons the SDK gives itself:

| Reason | When | Placed |
|---|---|---|
| `unreachable` | No usable answer within 2.5 seconds: a timeout, a 429 or 5xx twice, or an unreadable answer. | No. A local BLOCK. |
| `unverified` | The answer failed a check (signature, key, request hash, clock, shape), or it’s about other order fields or another quantity than the ones sent. | No, and nothing is reported. A local BLOCK. |
| `exits-only:<why>` | Exits-only refused a sell while reTrade was unreachable, and says why. | No. A local BLOCK. |
| `exit` | Exits-only placed a sell while reTrade was unreachable. | Yes. A local ALLOW. |
| `shadow-unreachable`, `shadow-unverified` | In shadow mode, the original order was placed without a usable answer. | Yes. A local BLOCK. |
| `expired`, `stopped` | An ALLOW or CUT withdrawn before the broker call: its time ran out, or a stop is engaged. | No. Reported as withdrawn. |
| `already-used` | The claim kit shows the decision was already used. | No. |
| `broker-rejected` | The broker definitely refused the order. | No. Reported as rejected. |
| `broker-outcome-unknown` | The submit’s outcome is unknown, and `find` found nothing. | Unknown. Never send it again. |