错误码

两种错误格式 — Web v1 plain text，FAPI 标准 JSON。按调用接口选择对应表格。

Web v1

本节所有 /v1/* 路由的错误都以纯文本响应体返回 —— 整个 body 就是错误信息。（wallet、deposit、solvency 路由则返回 { "error": "..." } JSON。）

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

side must be BUY or SELL

HTTP	典型原因
400	参数校验失败：side 非法、leverage 超出 1–100、路径中的 UUID 非法、price / qty 非正、未知 symbol、TP/SL 在开仓价错误一侧、提现的 amount / asset / 目标地址 / idempotency_key 非法。POST /v1/orders 上 trading service 的所有前置条件失败也是 400：insufficient available balance、market … is not active、trading paused (IF threshold)。
401	missing bearer token / invalid session —— 没有有效的 Authorization: Bearer <session_token>（来自 POST /v1/wallet/verify）。
403	not order owner；withdrawal permission denied；钱包托管账户（现货提现已禁用）；dev tools 未开启时访问按 user_id 的 /v1/account/{user_id}/…、/v1/positions/{user_id}/…。
404	未知 order_id（或已成交）/ withdrawal_id；dev-tools 路由未挂载。
408	请求超过 gateway 的 30 秒超时。
409	POST /v1/withdrawals：ledger 前置条件不满足（如 insufficient spot balance）。POST /v1/orders：trading service 返回 gRPC AlreadyExists / Aborted（idempotency_key 重发不会 409 —— 会返回原来的 order_id）。
413	请求体超过 1 MiB。
422	JSON 请求体无法反序列化（缺必填字段、类型错）。
500	DB 错误或后端异常（包括账户 / 持仓查询时 ledger 返回的任何错误）。
502	下游不可达 / 未映射的错误（bridge、funding-scheduler、提现的其他 gRPC 错误 —— 包括同一 idempotency_key 配不同内容重发）。
503	Trading service 挂掉；提现手续费报价不可用 / 过期；提现资格检查不可用。
504	下游 gRPC 超时；提现请求超时（15 秒）。

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（也用于未知 symbol、非法 side、不支持的 type）。
400	-1102	Mandatory parameter missing/empty（缺 signature 也是这个）。
422	-2010	Insufficient balance.
422	-2011	Order does not exist.
400	-2014	API-key format invalid.
401	-2015	Invalid API-key / IP / permissions.

常见误区

• -1021 — 时钟漂了。先用 date -u 校验，修 NTP 而不是调大 recvWindow。
• -1022 — secret 错、参数顺序对不上、缺 signature= 前缀。可对 标准签名向量 比对。
• -2010 — 可用 USDC < 所需 notional / LEVERAGE_V1。查余额。
• 刚下单就 -2011 — 竞态（下单→瞬间成交→查询）。当成「已经完成」处理。