Error Codes

All REST responses share the same shape: { "code": N, "data": { ... }, "timestamp": "...", "request_id": "..." }. On error, data is replaced by message. See Base URLs.

Error Code Reference

Code	HTTP	Category	Description
`0`	`200`	Success	Operation completed successfully
`1000`	`401`	Auth	`invalid_request` — malformed auth request
`1001`	`401`	Auth	`invalid_client` — unknown `client_id`, bad `client_secret`, or bad `passphrase`
`1002`	`401`	Auth	`token_expired` — bearer token past its `expires_in` window
`1003`	`401`	Auth	`token_revoked` — bearer token was revoked
`1004`	`401`	Auth	`not_authenticated` — missing `Authorization` header
`1005`	`400`	Auth	`unsupported_grant_type` — only `client_credentials` is supported
`1006`	`403`	Auth	`insufficient_scope` — token lacks required scope
`1100`	`500`	System	Internal server error
`1101`	`400`	System	Invalid JSON format
`1102`	`415`	System	Invalid or missing `Content-Type`
`1200`	`409`	Account	Account already exists
`1201`	`404`	Account	Account not found
`1300`	`500`	Database	Database operation failed
`1301`	`409`	Database	Database constraint violation
`1400`	`404`	Trading	Order not found or in a terminal state
`1401`	`403`	Trading	Order belongs to a different account
`1402`	`400`	Trading	Order type does not support the requested operation
`1403`	`400`	Validation	Missing or invalid required fields
`1404`	`409`	Trading	`duplicate_client_order_id` — `client_order_id` collides with another live order
`1405`	`503`	Trading	Book full — per-symbol order book capacity reached
`1406`	`400`	Trading	No counterparty available
`1407`	`400`	Trading	Insufficient liquidity — FOK order cannot be fully filled
`1410`	`400`	Risk	Margin insufficient
`1411`	`400`	Risk	Position limit exceeded
`1412`	`400`	Risk	Account in liquidation; new orders blocked
`1413`	`400`	Risk	Requested leverage above instrument `max_leverage`
`1414`	`410`	Risk	`instrument_halted` — instrument not currently accepting orders
`1429`	`429`	Rate Limit	Rate limit exceeded — see Rate Limits
`1430`	`400`	Trade Rules	Trade rule violation (minimum notional, quote rest period)
`1500`	`500`	System	Unexpected internal server error
`1501`	`503`	System	Service unavailable
`1502`	`202`	System	Service degraded — order queued; higher latency expected
`1503`	`503`	System	Temporarily unavailable — matching engine paused, retry later

HTTP Status Codes

Status	Description
`200`	Success
`202`	Accepted — request queued (see System Status)
`204`	No content (e.g. successful token revoke)
`304`	Not Modified (conditional `GET`, see Get Instruments)
`400`	Bad request
`401`	Unauthorized
`403`	Forbidden
`404`	Not found
`409`	Conflict (idempotency / constraint)
`410`	Gone / halted (instrument status)
`415`	Unsupported media type
`429`	Rate limited
`500`	Server error
`503`	Service unavailable

Error Response Example

{
  "code": 1410,
  "message": "Margin insufficient: available 1200.00 USDC, required 5000.00 USDC",
  "timestamp": "2026-04-20T10:30:00.123Z",
  "request_id": "req_01HXYZ..."
}

Handling Errors

Inspect code — HTTP status is a coarse hint, code is the authoritative classifier.
Auth (1000–1006) — refresh the bearer via POST /auth/token, then retry.
Validation (1403, 1101–1102) — fix the request; retries will keep failing.
Trading (1400–1407, 1414) — inspect message; 1404 means use a fresh client_order_id; 1407 means switch from FOK to IOC or reduce size.
Risk (1410–1413) — check margin and position state via GET /positions before retrying. See Margin & Liquidation and Pre-Trade Risk Validation.
Rate limit (1429) — back off exponentially; rate-limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) tell you when to retry.
Degraded (1502) — your order is queued; do not resubmit.
System (1500–1501, 1503) — retry with exponential backoff starting at 1s.