Errors
The status codes the contract declares, the rate-limit headers, and how a 401 deliberately tells you nothing.
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
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:
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.
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.
Error model
Last updated