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

# Error reference

> Every error code the Bullionwale API returns, with its HTTP status, the environments it occurs in, and what to do.

Every refusal is an HTTP status and a body of the form `{"detail": {"code": ..., "message": ...}}`. Branch on `detail.code`; it is stable. See [Errors](/errors) for the format, how to handle a code you do not know, and troubleshooting.

"Env." says where a code can occur: **both** environments, or **prod** (production only).

| Code | Status | Env. | Meaning | What to do |
| - | - | - | - | - |
| `missing_credential` | 401 | both | No `X-API-Key` header. | Send the key in `X-API-Key`. |
| `malformed_credential` | 401 | both | The value is not shaped like an API key. | Check that the whole key was copied, with no spaces or quotes. |
| `wrong_tenant` | 401 | both | The key belongs to a different broker. | Use a key Bullionwale issued for your account. |
| `wrong_environment` | 401 | both | A test key on a production path, or a live key on a test path. | Match the key to the base path. |
| `invalid_credential` | 401 | both | Unknown key or wrong secret. | Check the key; ask for a new one if needed. |
| `credential_revoked` | 401 | both | The key was revoked. | Ask for a new key. |
| `credential_rotated` | 401 | both | The key was replaced and its overlap ended. | Use the new key. |
| `credential_expired` | 401 | both | The key expired. | Ask for a rotation. |
| `api_access_disabled` | 403 | both | API access is off for your account. | Contact Bullionwale. |
| `account_inactive` | 403 | both | Your account is not active. | Contact Bullionwale. |
| `insufficient_scope` | 403 | both | The key lacks the scope this call needs. | Use a key with the scope, or ask for it. See [Scope reference](/scopes). |
| `production_trading_disabled` | 403 | prod | Production trading is not available to you right now. `detail.reason` is `deploy`, `global` or `account`. | See [Production access](/production-access#when-production-orders-are-refused). |
| `production_prerequisites_unmet` | 503 | prod | Production trading is paused by Bullionwale. Nothing was booked. | Retry later. Nothing to change on your side. |
| `auth_throttled` | 429 | both | Too many failed authentications from your address. | Wait `Retry-After`; fix the failing key. |
| `rate_limited` | 429 | both | A rate budget is used up. | Wait `Retry-After`; retry with the same `Idempotency-Key`. |
| `rate_limiter_unavailable` | 503 | both | Order rate limiting is temporarily unavailable, so orders are refused. Reads keep working. | Wait `Retry-After`; retry with the same `Idempotency-Key`. |
| `invalid_request` | 422 | both | The body or a parameter is invalid. `detail.errors` lists each problem and its location. | Fix the request. |
| `idempotency_key_required` | 400 | both | `POST /orders` without an `Idempotency-Key` header. | Send one. |
| `idempotency_key_reused` | 422 | both | This `Idempotency-Key` was used for a different order body. Nothing was booked. | Use a new key for a new order; check your records. |
| `order_not_found` | 404 | both | No such order on your account (or one the API does not show). | Check the id. See [Which orders you see](/api-reference/orders/overview#which-orders-you-see). |
| `delivery_not_found` | 404 | both | No such delivery request on your account. Test has none. | Check the id. See [Deliveries](/api-reference/deliveries/overview). |
| `order_rejected` | 409 | prod | The hedge refused the order. Nothing was booked. `detail.order_id` and `detail.order` show it. | Decide whether to place a new order with a new key. |
| `unknown_symbol` | 404 | both | No such symbol. | Check `symbol_code`. |
| `symbol_not_trading` | 400 | both | Trading is off for this symbol. | Try later or another symbol. |
| `invalid_side` | 400 | both | `trade_type` is not `buy` or `sell`. | Fix the request. |
| `side_not_offered` | 403 | both | Bullionwale does not offer this side for market orders. | Contact Bullionwale. |
| `rates_not_ready` | 503 | both | Rates are not loaded yet. | Retry shortly with the same key. |
| `no_live_price` | 400 | both | The symbol has no live price right now. | Try later. |
| `unpriced` | 400 | both | The symbol could not be priced. | Try later. |
| `stale_rate` | 503 | both | The rate is stale. | Retry shortly with the same key. |
| `trading_halted` | 403 | both | Bullionwale has halted trading. | Try later. |
| `symbol_frozen` | 400 | both | The symbol's price feed is frozen. | Try later. |
| `quantity_rule` | 400 | both | The quantity breaks the symbol's size rule. | Change the quantity. |
| `tradeability_unverified` | 503 | prod | Whether the symbol can be traded could not be checked. | Retry shortly with the same key. |
| `symbol_unavailable` | 503 | prod | The symbol is unavailable. | Retry later with the same key. |
| `group_trading_disabled` | 403 | both | Trading is off for your account's trading group. | Contact Bullionwale. |
| `group_quantity_rule` | 400 | both | The quantity breaks your trading group's size terms. | Change the quantity. |
| `pricing_unavailable` | 503 | both | Your price could not be computed. | Retry shortly with the same key. |
| `limit_exceeded` | 400 | both | The order would take your open position in that metal past your weight allocation. | Reduce the quantity or your position. See [Positions](/api-reference/positions/overview#how-the-allocation-works). |
| `out_of_stock` | 400 | prod | Not enough stock for this buy. | Reduce the quantity or try later. |
| `price_moved` | 409 | both | The live price moved beyond Bullionwale's tolerance from your `expected_price`. Nothing was booked. | Check the new price and send a new order with a new key. |
| `booking_conflict` | 409 | prod | Another booking on your account conflicted with this one. | Retry with the same `Idempotency-Key`. |
| `booking_unavailable` | 503 | prod | The order could not be recorded, so nothing was booked. | Retry with the same key. |
| `booking_busy` | 503 | prod | The booking waited too long behind your account's other bookings, so nothing was booked. | Wait `Retry-After`; retry with the same key. |
| `booking_not_completed` | 503 | prod | The booking failed and no booked order was found: nothing was booked yet. | Wait `Retry-After`; retry with the same key for the definitive answer. See [Outcomes after a failure](/idempotency#outcomes-after-a-failure). |
| `booking_outcome_unknown` | 503 | prod | The booking failed and its outcome could not be read. | Wait `Retry-After`; retry with the same key to get it. |
| `limit_order_not_found` | 404 | both | No such limit order on your account. | Check the id. |
| `limit_would_execute` | 400 | both | The limit's trigger price is at or past the current price, so it would execute at once. | Move the trigger (a buy below the current price, a sell above it), or place a market order. |
| `limit_order_not_pending` | 409 | both | The limit order was already triggered or cancelled, so it cannot be edited or cancelled. | Read it again. If it was triggered, its `order_id` names the order it became. |
| `limit_order_confirming` | 409 | prod | The limit order is `confirming`: its hedge is still being placed or cancelled. | Read it again in a few seconds; edit or cancel it once it is `pending`. |
| `limit_order_rejected` | 409 | prod | The limit order was not placed: the hedge refused it. `detail.limit_order_id` and `detail.limit_order` show it. | Decide whether to place a new limit order with a new key. |
| `limit_cancel_failed` | 503 | prod | The cancel did not complete, so the limit order is still `pending`. | Wait `Retry-After`, then send the cancel again. |
| `webhook_not_found` | 404 | both | No such webhook on your account in this environment. A test webhook is not visible on the production API, and the reverse. | Check the id and the base path. |
| `invalid_webhook_url` | 422 | both | The URL is not `https`, carries a user name, password or `#fragment`, does not resolve, or points at a private, loopback, link-local or metadata address. | Use a public `https` URL. |
| `invalid_event_type` | 422 | both | `events` is empty or names an unknown event type. | Pick from the event types listed on [Webhooks](/api-reference/webhooks/overview). |
| `webhook_limit_reached` | 409 | both | Your account already has the maximum number of webhooks in this environment. | Delete one first. |
| `webhook_inactive` | 409 | both | The webhook is paused, so it cannot be sent a test event. | Set `active` to `true` first. |


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