> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/guides/errors.md). # Errors The status codes the contract declares, the rate-limit headers, and why a 401 tells you nothing. Every generated endpoint page lists the statuses that operation declares. This page explains what each code means across the API, and the two places where the contract tells you little on purpose. ## Error model | Status | Meaning | Notes | | ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Success | 123 operations | | `201` | Created | 5 operations. `POST /orders`, `POST /orders/batch` and `POST /bridge/withdrawals`. | | `101` | Switching Protocols | The two WebSocket upgrade paths | | `400` | Validation error | 50 operations. The body carries a machine-readable `code` where the contract defines one, e.g. `invalid_window`, `bad_wallet`, `bad_agent`, `expiry_out_of_range`, `invalid_json`. Order rejections cover insufficient margin, invalid tick size, non-amendable orders, and margin breach. | | `401` | Authentication failed | 89 operations. **All 401 responses return the same opaque body, `{"code":"unauthorized"}`, on purpose, to prevent information leakage.** A 401 does not tell you *why*. A bad key, a bad signature, a stale timestamp, and an expired session look the same. Check your clock skew first. | | `403` | Forbidden | 25 operations. Jurisdiction-control refusals on order, funding, leverage, margin and bridge-withdrawal writes, which are permanent for the caller's origin, so do not retry. The admin endpoints (admin secret required). `POST /account/credit` when an operator has frozen crediting (`credits_frozen`). `EARLY_ACCESS_REQUIRED` on `GET /account/deposit-target`. Refused withdrawals on `POST /withdrawals`. `TRANSFER_ACCOUNT_INELIGIBLE` or `TRANSFER_OUTFLOW_BLOCKED` on the `/transfers` operations. On the order-cancel operations, also an agent key that is not active for the account (no such key, a key bound to another account, or an expired key). | | `404` | Not found, or not owned by you | 26 operations. Ownership failures return 404, not 403, so you cannot probe for other accounts' resources. | | `409` | Conflict | 7 operations. `duplicate_agent` on agent registration, which also covers a revoked address whose original expiry has not passed. A `client_id` already claimed by an order that is no longer resting, on order placement. The market-lifecycle admission gate on an amend. An `Idempotency-Key` reused with a different amount on `POST /bridge/withdrawals`. `TRANSFER_ID_CONFLICT` on `POST /transfers`. | | `422` | Unprocessable | 1 operation. `POST /account/margin-mode` with semantically invalid data, unknown fields, or a `margin_mode` other than `cross` or `isolated`. Malformed JSON is a `400`. | | `426` | Upgrade Required | 1 operation. `POST /account/deposit` when a verified service key sends the credited account in the `X-Account-Id` header. Send `account_id` in the signed body instead. | | `429` | Rate limit exceeded | 74 operations. See below. | | `500` | Internal error | 3 operations. `INTERNAL_ERROR` on `POST /auth/login` when the session store write fails, and an unexpected internal error on `GET` and `POST /account/margin-mode`. | | `502` | Upstream unavailable | 14 operations. On `/account/summary` and `/account/state`, `authoritative_margin_unavailable`: the engine-authoritative margin view is temporarily unavailable. Endpoints that derive balances from it **fail closed** and return the error rather than a locally estimated, potentially unsafe figure. Transient, so retry after a short delay. The rest are `BAD_GATEWAY` on the referral reads, `FUNDING_SOURCE_*` on the funding snapshot, a failed downstream step on `POST /bridge/withdrawals`, and `TRANSFER_*` outcomes on the `/transfers` operations. | | `503` | Service unavailable | 11 operations. `DEPOSIT_TARGET_MISCONFIGURED` on `GET /account/deposit-target`, `REFERRALS_UNAVAILABLE` on the referral reads, `TRANSFERS_UNAVAILABLE` on the `/transfers` operations, withdrawals not available on `POST /bridge/withdrawals`, and `MarketUnavailable` on `POST /account/margin` when risk sees no position while a commit on that market is still being made durable (nothing changed; retry). | An operation is one path and method in `openapi.json`, with each `/api/v1` twin counted separately. The rows above name only the unprefixed path, so each count also includes the `/api/v1` twins the prose leaves out. A count is the number of operations that declare that status. To recompute them, run this from the repository root: ```bash python3 -c 'import json, collections; d = json.load(open("eng/apps/exchange/api/openapi.json")); print(sorted(collections.Counter(code for item in d["paths"].values() for method, op in item.items() if method in ("get", "put", "post", "delete", "patch") for code in op.get("responses", {})).items()))' ``` ### 429 and the rate-limit headers A `429` body looks like `{"code":"RateLimitExceeded","tier":"Pro"}` and the response carries: | Header | Meaning | | ----------------------- | ----------------------------------------- | | `X-RateLimit-Limit` | Requests per second allowed for your tier | | `X-RateLimit-Remaining` | Requests remaining in the current window | | `X-RateLimit-Reset` | Unix timestamp when the limit resets | | `Retry-After` | Seconds to wait before retrying | Pace from the `X-RateLimit-*` headers rather than retrying blindly. Two endpoints reuse `429` for a non-rate-limit meaning: `POST /account/credit` (daily credit allowance exhausted, resets at midnight UTC) and `POST /faucet` (cooldown not elapsed, or cumulative cap reached). For tier ceilings and connection caps, see [Rate-Limits](https://docs.nexus.xyz/exchange/apis-and-rates/rate-limits). ## CCXT compatibility ### API version support The version identifier is the released spec tag of this contract. The edge publishes the versions it accepts at `/metadata`, which the edge serves and which is **not** an operation in this contract. It returns `current_api_version` (latest tag served) and `min_api_version` (oldest tag still accepted), so clients and agents can read the support window programmatically. Before 1.0 (`v0.x.y`), breaking changes are frequent and `min_api_version` may advance with any breaking release. A released tag stays supported for at least **14 days** after the release that supersedes it, and that window widens after 1.0. A request whose `X-Nexus-Api-Version` names a recognized tag older than `min_api_version` receives a machine-readable `426 Upgrade Required` (`api_version_unsupported`) with a link to the current spec, so tooling can detect the skew and upgrade. Because the header is unauthenticated, this gate is a compatibility aid, not a security control. Spoofing the value only relaxes it. See also [API Versioning](https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.nexus.xyz/api-reference/guides/errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.