Error responses

Failures use the same envelope as successes, with success: false and an error object:

{
  "success": false,
  "error": {
    "code": "TRADE_INSUFFICIENT_MARGIN",
    "codeNum": 13002,
    "message": "Insufficient margin",
    "details": { "required": "142.50", "available": "98.11" }
  },
  "meta": { "requestId": "req_b2fbe365c9604884a4d202b451c57e45", "timestamp": 1790094673430 }
}

code is the stable identifier. codeNum is the same thing as a 5-digit integer for clients that prefer numeric switches. message is human-facing and may be reworded at any time — never match on it. details is present when there is structured context worth acting on (which market, how much was missing) and absent otherwise.

Families

The first two digits tell you which subsystem refused, which is usually enough to decide whether to fix the request, fix the account, or retry.

Range	Family	Meaning
`100xx`	`REQ_*`	malformed request — bad JSON, missing field, invalid market/side/price/size/TIF
`1005x`	`RESOURCE_*`	generic not-found / already-exists
`110xx`	`AUTH_*`	credential, signature, timestamp, replay
`111xx`	`PERM_*`	key lacks the right, IP not allowed, account blocked
`120xx`	`ACCT_*`	account state — suspended, KYC, withdrawal locks
`130xx`	`TRADE_*`	admission control — margin, size, price band, market state, slippage
`131xx`	`ORDER_*`	order lifecycle — not found, already filled/cancelled, duplicate client id
`140xx`	`POS_*`	position state — not found, already closed, TP/SL conflicts
`150xx`	bridge, withdraw, transfer, fund, championship, payment, on-ramp, strategy
`170xx`	`PRED_*`	prediction markets
`180xx`	`ADV_*`	advanced orders — duration, interval, trigger price, already triggered
`190xx`	`RATE_LIMIT_*`	see Rate limits
`250xx`	risk engine — leverage, margin, liquidation phase, reduce-only, IOC no-fill
`415xx`	portfolio risk — deficit risk, warning zone
`500xx`	`SYS_*`	internal, maintenance, overload, timeout, DB, chain, global halt

The ones you will actually hit

Code	Num	What it means in practice
`REQ_INVALID_PARAMS`	10001	a value failed validation; `details` names the field
`AUTH_INVALID_SIGNATURE`	11003	canonical payload built wrong — see Authentication
`AUTH_TIMESTAMP_EXPIRED`	11004	host clock more than 30 s off
`AUTH_REPLAY_DETECTED`	11013	identical signature resent; re-sign with a fresh timestamp
`PERM_NO_TRADING`	11101	read-only key
`TRADE_INSUFFICIENT_MARGIN`	13002	order needs more margin than the account has free
`TRADE_SIZE_TOO_SMALL`	13003	below the market's minimum size or notional
`TRADE_PRICE_DEVIATION`	13005	limit price outside the venue price band around mark
`TRADE_MARKET_CLOSED`	13006	session-bound market (equities, options on equities) outside hours
`TRADE_POST_ONLY_FAIL`	13009	post-only order would have taken
`TRADE_SLIPPAGE_EXCEEDED`	13016	fill would have been worse than your `slippage` / `maxSlippageBps` bound
`TRADE_MARKET_NOT_FOUND`	13014	symbol does not exist — check spelling against `/system/info`
`ORDER_DUPLICATE_CLIENT_ID`	13106	`clientOrderId` already used; the first order stands
`POS_TPSL_EXISTS`	14005	position already protected; resend with `replace: true` to take over
`SYS_OVERLOAD` / `SYS_TIMEOUT`	50003 / 50004	transient — retry with backoff
`SYS_MAINTENANCE` / `SYS_GLOBAL_HALT`	50002 / 50009	trading is stopped platform-wide; do not retry in a loop

Retry rules

Safe to retry with backoff: 50003, 50004, 50005, 50007, 13015 (concurrency conflict), 13018 (engine not ready yet).
Never retry blindly on order placement. A network timeout does not tell you whether the order reached the book. Always send a clientOrderId, then either retry with the same id (the exchange rejects the duplicate rather than double-filling) or reconcile with GET /api/v1/perp/orders.
Do not retry 110xx, 111xx, 100xx or 13001–13014 unmodified — the request or the account state has to change first.
Log meta.requestId on every non-2xx. It is the only handle that resolves to the exact server-side log line.