> 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 Every generated endpoint page lists the statuses that operation declares. This page is the model behind them — what each code means across the surface, and the two places the contract is deliberately uninformative. ## Error model | Status | Meaning | Notes | | ------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Success | 92 operations | | `201` | Created | 4 operations — resource creation on the bridge surface | | `101` | Switching Protocols | The two WebSocket upgrade paths | | `400` | Validation error | 14 operations. 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 | 66 operations. **All 401 responses return the same opaque body — `{"code":"unauthorized"}` — deliberately, to prevent information leakage.** A 401 does not tell you *why*: bad key, bad signature, stale timestamp, and expired session are indistinguishable. Check your clock skew first. | | `403` | Forbidden | 5 operations — the admin endpoints (admin secret required) and `POST /account/credit` when crediting is administratively frozen. | | `404` | Not found, or not owned by you | 17 operations. Ownership failures are reported as 404, not 403 — you cannot probe for other accounts' resources. | | `409` | Conflict | 1 operation — `duplicate_agent` on agent registration. | | `429` | Rate limit exceeded | 58 operations. See below. | | `502` | Upstream unavailable | 4 operations. `authoritative_margin_unavailable` — the engine-authoritative margin view is temporarily unavailable, and endpoints that derive balances from it **fail closed**, returning the error rather than a locally-estimated, potentially unsafe figure. Transient; retry after a short delay. | ### 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` — served by the edge, **not** an operation in this contract — returning `current_api_version` (latest tag served) and `min_api_version` (oldest tag still accepted), so clients and agents can discover the support window programmatically. Pre-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; 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 courtesy, not a security control — spoofing the value only relaxes it. See also [API Versioning](https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning). ## Error model --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.