Error Codes

Two error envelopes — Web v1 plain text, FAPI Standard JSON. Pick the table that matches the surface you're calling.

Web v1

All /v1/* routes on this page return errors as a plain-text body — the message is the whole body. (The wallet, deposit and solvency routes instead return { "error": "..." } JSON.)

HTTP/1.1 400 Bad Request
content-type: text/plain

side must be BUY or SELL

HTTP	Typical causes
400	Validation failure: bad side, leverage outside 1–100, malformed UUID in the path, non-positive price / qty, unknown symbol, TP/SL on the wrong side of the entry price, withdrawal amount / asset / destination / idempotency_key invalid. Also every trading-service precondition failure on POST /v1/orders: insufficient available balance, market … is not active, trading paused (IF threshold).
401	missing bearer token / invalid session — no valid Authorization: Bearer <session_token> (from POST /v1/wallet/verify).
403	not order owner; withdrawal permission denied; wallet-funded account (spot withdrawals disabled); user-scoped /v1/account/{user_id}/… and /v1/positions/{user_id}/… routes when dev tools are off.
404	Unknown order_id (or already filled) / withdrawal_id; dev-tools routes when not mounted.
408	Request exceeded the gateway's 30 s timeout.
409	POST /v1/withdrawals: ledger precondition failed (e.g. insufficient spot balance). POST /v1/orders: gRPC AlreadyExists / Aborted from the trading service (an idempotency_key replay does not 409 — it returns the original order_id).
413	Request body over 1 MiB.
422	JSON body fails to deserialize (missing required field, wrong type).
500	DB error or unexpected failure (including any ledger error on the account/position lookups).
502	Downstream unreachable / unmapped error (bridge, funding scheduler, other withdrawal gRPC errors — including an idempotency_key reused with a different payload).
503	Trading service down; withdrawal fee quote unavailable/stale; withdrawal eligibility check unavailable.
504	Downstream gRPC deadline exceeded; withdrawal request timed out (15 s).

FAPI

HTTP/1.1 422 Unprocessable Entity
content-type: application/json

{ "code": -2010, "msg": "Account has insufficient balance for requested action." }

HTTP	code	msg
500	-1000	An unknown error occurred while processing the request.
401	-1021	Timestamp for this request is outside of the recvWindow.
401	-1022	Signature for this request is not valid.
400	-1100	Illegal characters in parameter (also: unknown symbol, invalid side, unsupported type).
400	-1102	Mandatory parameter missing/empty (also: missing signature).
422	-2010	Insufficient balance.
422	-2011	Order does not exist.
400	-2014	API-key format invalid.
401	-2015	Invalid API-key / IP / permissions.

Common pitfalls

• -1021 — your clock is drifty. Run date -u to check. Fix NTP rather than enlarging recvWindow.
• -1022 — wrong secret, parameter-order mismatch, or missing signature= prefix. Validate against the canonical signing vector.
• -2010 — available USDC < required notional / LEVERAGE_V1. Check balance.
• -2011 on a fresh order — race (placed → instantly filled → queried). Treat as "already done."