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

# Errors

> Error codes, venue codes and what to do about each.

Every error uses the same envelope:

```json theme={"dark"}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<venue message>",
    "details": {
      "venue_code": "INSUFFICIENT_BALANCE",
      "order_id": "<order id>"
    }
  },
  "meta": { "requestId": "<request id>" }
}
```

| Field | Meaning |
| - | - |
| `error.code` | A stable `SCREAMING_SNAKE_CASE` code. Branch on this, not on `message`. |
| `error.message` | A readable explanation. It may change. |
| `error.details.venue_code` | When a venue refused the order: the specific reason, for example `INSUFFICIENT_BALANCE`. |
| `error.details.order_id` | When the error concerns an order Lean recorded: its Lean ID. Read it back with `GET /v1/orders/{id}`. |
| `error.details.reason` | On `422`: why Lean refused the order. On `403 FORBIDDEN` from `POST /v1/routed-orders/{id}/execute`: `ACCOUNT_NOT_DELEGATED`. On `503 FEATURE_DISABLED` at placement: `LIVE_TRADING_DISABLED` or `TRADING_PAUSED`. |
| `error.details.scope` | With `TRADING_PAUSED`: what is paused, `api_key` or `trading_account`. |
| `meta.requestId` | Also sent as the `X-Request-ID` header. Include it when you report a problem. |

`details` can carry more fields specific to the venue. Ignore fields you do not recognize.

`details` takes one of two shapes:

* When the body, query or path failed validation, `details` is a list with one entry per problem:
  `path` names the field, with nested fields joined by `.` (such as `venues.0`), and `message` says
  what is wrong with it. `error.message` names the first problem as `path: message`, and adds how
  many more `details` lists.
* Otherwise `details` is an object with the fields above, or it is left out.

```json theme={"dark"}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "market_ids: At most 25 market ids per request; split larger sets across requests",
    "details": [
      {
        "path": "market_ids",
        "message": "At most 25 market ids per request; split larger sets across requests"
      }
    ]
  },
  "meta": { "requestId": "<request id>" }
}
```

## Codes

| HTTP | `code` | When | What to do |
| - | - | - | - |
| 400 | `VALIDATION_ERROR` | Malformed body, a body sent without `Content-Type: application/json`, a query parameter the endpoint does not take, a price outside (0, 1), a size the venue cannot take, a bad cursor or one another list issued, a closed market, a value in a market ID field that is neither a market ID nor a venue symbol, or a venue symbol that names more than one market. `details` lists each invalid field when the body or query failed validation. | Fix the request. |
| 401 | `UNAUTHORIZED` | Missing, malformed, unknown, expired or revoked key. | Check the key. |
| 402 | `VALIDATION_ERROR` | The venue account cannot cover the order. `details.venue_code` is `INSUFFICIENT_BALANCE`. | Reduce the size or add funds. See [Funding](https://docs.lean.xyz/funding.md). |
| 403 | `FORBIDDEN` | The key lacks the scope, the account has no API access, or trading on the venue is not available to the account. | Use a key with `trade`, or check the account. |
| 403 | `FORBIDDEN` | On a live Kalshi or Polymarket US order: the user has not connected an API key for that venue in the Lean app. | Connect the venue's API key in the Lean app, or leave the venue out with `venues`. See [Kalshi and Polymarket US](https://docs.lean.xyz/orders.md#kalshi-and-polymarket-us). |
| 403 | `FORBIDDEN` | On `POST /v1/routed-orders/{id}/execute` with `"authorization": "delegated"` and a live key: the account has not enabled trading in the Lean app. `details.reason` is `ACCOUNT_NOT_DELEGATED`. | Enable trading in the Lean app, or send a `payment_signature` instead. See [Advanced: self-signed routed orders](https://docs.lean.xyz/routed-orders.md#letting-lean-sign). |
| 400 | `VALIDATION_ERROR` | On `POST /v1/withdrawals`: the `source` and `destination` are not a pair the venue pays out on, or `destination.address` does not suit `destination.chain`. Polymarket pays `pusd` out as `usdc`, and Hyperliquid pays `usdc` out as `usdc`, on `polygon`, `arbitrum`, `base`, `optimism`, `ethereum`, `bsc` or `solana`. The message says what is supported. | Send a supported pair, with a `0x` address for every chain except `solana`. See [Withdrawals through the API](https://docs.lean.xyz/funding.md#withdrawals-through-the-api). |
| 403 | `FORBIDDEN` | On `POST /v1/withdrawals`: the key lacks the `withdraw` scope, or a live key's account has not enabled trading in the Lean app (`details.reason` is `ACCOUNT_NOT_DELEGATED`). | Use a key created with `withdraw`, or enable trading in the Lean app. See [Withdrawals through the API](https://docs.lean.xyz/funding.md#withdrawals-through-the-api). |
| 400 | `VALIDATION_ERROR` | On `POST /v1/stop-losses`: the trigger price, slippage limit, quantity or expiry does not fit the market, the best bid already meets the trigger (a `stop_loss` at or above the bid or on a market with no bid, a `take_profit` at or below the bid), or the quantity is more than the account holds beyond its other stop losses and resting sells. On `DELETE /v1/stop-losses/{id}`: the stop loss has already ended. | Fix the request, or read the stop loss back. See [Stop losses and take profits](https://docs.lean.xyz/stop-losses.md). |
| 400 | `VALIDATION_ERROR` | On `POST /v1/limit-chases`: the offset, price limit, quantity or expiry does not fit the market, a test key's buy costs more than its simulated cash on the venue, or a sell is more than the account holds beyond its resting sells and stop losses. On `DELETE /v1/limit-chases/{id}`: the limit chase has already ended. | Fix the request, or read the limit chase back. See [Limit chases](https://docs.lean.xyz/limit-chases.md). |
| 404 | `NOT_FOUND` | Unknown market ID, a quote for a market with no venue listing, an order not on this key's account, an order from the other mode (a live order read with a test key, or the other way round), or a path or method no endpoint serves. A request without a valid key gets `401` first. | Check the ID, the key and the path. |
| 409 | `CONFLICT` | `client_transfer_id` reused with a different body. `details.transfer_id` is the original. | Read the transfer back. |
| 409 | `CONFLICT` | `client_order_id` reused with a different body (`details.order_id` is the original), or a cancel of a finished order or one the venue has not acknowledged yet. Test orders are always finished. | Read the order back. |
| 409 | `CONFLICT` | On `POST /v1/withdrawals`: `client_withdrawal_id` reused with a different venue, amount or destination (`details.withdrawal_id` is the original), the venue wallet is not set up, or another Hyperliquid withdrawal for the account is still settling (`details.reason` is `WITHDRAWAL_IN_PROGRESS`). | Read the withdrawal back, or wait for the other one to settle. |
| 409 | `CONFLICT` | On `PATCH /v1/orders/{id}`: the order cannot be amended. `details.reason` is `ORDER_NOT_OPEN` (it finished), `ORDER_REPLACED` (`details.replaced_by_order_id` names the order that replaced it), `ORDER_NOT_AMENDABLE` (it is routed, split or `ioc`) or `REPLACEMENT_PENDING` (the order's cancel was requested and nothing was placed in its place yet; send the same amend again once it reads `canceled`). | Read the order back. See [Amend an order](https://docs.lean.xyz/orders.md#amend-an-order). |
| 409 | `CONFLICT` | A venue has stopped trading the market, so it has no book to read, quote or fill against. `details.reason` is `MARKET_NOT_TRADABLE`. | Use a leg whose `tradable` is `true`, or another market. |
| 409 | `CONFLICT` | On placement: a venue the order needs is not ready for API orders on this account, for example its wallet changed or its signing is not delegated. | Fix the account's venue setup, then retry with the same `client_order_id`. |
| 422 | `VALIDATION_ERROR` | Lean refused the order before it reached a venue. See `details.reason` below. | Change the order, or add funds. |
| 429 | `RATE_LIMITED` | Over 5 requests a second per key (bursts of 20), or the venue throttled the request. Cancels have their own budget of 10 a second (bursts of 40). | Wait for `Retry-After` (seconds) when it is sent, then retry. |
| 500 | `INTERNAL_ERROR` | An unexpected error inside Lean. | Retry reads. For an order, read it back by `client_order_id` first. Report `meta.requestId`. |
| 503 | `UPSTREAM_ERROR` | On placement: a venue failed before anything was placed. On a quote or preview: the venue failed or answered with something Lean could not read. | Nothing was placed. Look the order up by `client_order_id` before you send it again. |
| 503 | `UPSTREAM_ERROR` | On a quote, preview or order that needs a Polymarket US book: Lean has not loaded that market's book yet. `Retry-After` is sent. Nothing was placed. | Wait for `Retry-After`, then send the same request again. |
| 503 | `UPSTREAM_ERROR` | On `GET /v1/orders/{id}`: a venue could not be read or reached, and the stored order is unchanged. On a cancel: a venue could not be reached, so its leg was not canceled, though legs on other venues may be. | Read the order again. Do not assume a cancel happened until the order reads `canceled`. |
| 503 | `UPSTREAM_ERROR` | A venue or a Lean dependency timed out or dropped the connection, or the request lost a database conflict. `Retry-After` is sent. On placement the order may or may not have reached the venue. | Wait for `Retry-After`, then retry. For an order, look it up by `client_order_id` first and resend with the same `client_order_id`. |
| 503 | `UPSTREAM_ERROR` | On `POST /v1/withdrawals`: the venue could not be read or could not prepare the withdrawal. Nothing was recorded or paid. | Retry with the same `client_withdrawal_id`. |
| 503 | `UPSTREAM_ERROR` | On `POST /v1/stop-losses`: the market's book could not be read to check the trigger price against the best bid. Nothing was created. | Retry. See [Triggers the bid already meets](https://docs.lean.xyz/stop-losses.md#triggers-the-bid-already-meets). |
| 503 | `FEATURE_DISABLED` | On placement with a live key: Lean has paused live trading platform wide. `details.reason` is `LIVE_TRADING_DISABLED`. | Retry later, or keep building with a test key. Reads and cancels still work. See [Test mode](https://docs.lean.xyz/test-mode.md#go-live). |
| 503 | `FEATURE_DISABLED` | On placement: this key or its trading account is paused. `details.reason` is `TRADING_PAUSED` and `details.scope` is `api_key` or `trading_account`. | Resume from the Lean dashboard. Reads and cancels still work. See [Pause trading](https://docs.lean.xyz/orders.md#pause-trading). |
| 503 | `FEATURE_DISABLED` | On a quote: routing is not available. On an order: a venue's order placement is switched off. | Retry later. |
| 503 | `FEATURE_DISABLED` | On a transfer with a live key: live transfers are not available yet. `details.reason` is `LIVE_TRANSFERS_UNAVAILABLE`. Nothing moved. | Use a test key, or pay from the other venue with `POST /v1/orders`. See [Transfers](https://docs.lean.xyz/transfers.md). |
| 503 | `INTERNAL_ERROR` | Lean or the venue is temporarily unavailable, for example Lean cannot check the key's rate limit. Lean does not serve a request it cannot rate limit. | Retry later with the same `client_order_id`. |

Every code is one of `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`,
`RATE_LIMITED`, `UPSTREAM_ERROR`, `INTERNAL_ERROR` and `FEATURE_DISABLED`.

The error schema in the OpenAPI spec also lists `CONDITIONAL_SELL_REJECTED` and
`CONDITIONAL_SELL_ACTIVE`. They belong to conditional sells in the Lean app, and no `/v1` endpoint
returns them.

New `details.reason`
and `details.venue_code` values can appear without a new version; treat one you do not recognize by
its HTTP status. See [Versioning](https://docs.lean.xyz/versioning.md).

### `details.reason` on 422

| `details.reason` | Meaning |
| - | - |
| `ORDER_NOTIONAL_LIMIT` | A buy's `quantity × limit_price` is above the key's per order limit. A sell is never refused for it. |
| `DAILY_NOTIONAL_LIMIT` | The buy, limit chase or transfer would push the key over its rolling 24 hour limit, which all of them share. Sells count toward the day but are never refused for it. |
| `BELOW_VENUE_MINIMUM` | The order is below the minimum of every venue that could place it. `details.min_order_notional_micros` is the smallest notional accepted. On a transfer: `amount_usd` is below the route minimum, `details.minimum_usd`. |
| `INSUFFICIENT_FUNDS` | The trading account cannot pay for the order on any venue that could place it, and Lean could not pay for it with cash from the other venue. On a transfer: `from_venue` can't send `amount_usd`; `details.available_usd` is what it can send. |
| `NO_EXECUTABLE_VENUE` | No venue can place this market today. On `POST /v1/stop-losses` and `POST /v1/limit-chases`, the market cannot be traded on the `venue` you named. |
| `VENUE_NOT_ALLOWED` | `venues` names a venue the trading account does not allow, or the account allows no venue that lists the market. `details.allowed_venues` lists the venues it allows. On `POST /v1/stop-losses` and `POST /v1/limit-chases`, the account does not allow the `venue` you named. |
| `INSUFFICIENT_HOLDINGS` | A sell for more shares than the trading account holds. |
| `INSUFFICIENT_DEPTH` | An `all_or_none` order the books can't fill in full within `limit_price` and the slippage bound. |
| `ROUTE_NOT_EXECUTABLE`, `LIMIT_BELOW_ROUTE_PRICE` | On a [routed order](https://docs.lean.xyz/routed-orders.md): no route can fill the whole quantity within the limit. |
| `POST_ONLY_WOULD_CROSS` | A `post_only` order would trade at once against the books. `details.executable_quantity` is how much would fill. See [Post only orders](https://docs.lean.xyz/orders.md#post-only-orders). |
| `WITHDRAWAL_LIMIT_EXCEEDED` | A withdrawal is above the key's single withdrawal limit. `details.limit_usd` is the limit. |
| `DAILY_WITHDRAWAL_LIMIT_EXCEEDED` | A withdrawal would push the key over its rolling 24 hour withdrawal limit. `details.limit_usd` is the limit and `details.used_usd` what the key has withdrawn in that time. |
| `INSUFFICIENT_BALANCE` | A withdrawal is above the cash available on the venue. `details.available_usd` is what can be withdrawn. |

> [!NOTE]
>
> Never resend an order with a new `client_order_id` after a timeout, an error, or an `unconfirmed`
> status. Look it up by the original ID first. A venue outcome after placement is a `200` with the
> order's `status`, not an error. See [What placement returns](https://docs.lean.xyz/orders.md#what-placement-returns).


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