错误码

现货 API 以 {"error": "<STRING_CODE>"} 格式返回错误，并附带相应 HTTP 状态码。本页按类别列出现货子系统发出的所有错误码。

鉴权与权限

HTTP	error	触发条件
401	(响应体为空)	JWT 缺失 / 无效、HMAC 签名缺失 / 错误，或 timestamp 超出服务器时间 ±5000 ms 范围。
403	API Key permission denied	API Key 调用方访问了 POST /spot/transfer 或 POST /spot/withdraw/request（仅限 JWT）。
403	FORBIDDEN	目标资源（订单、提币申请）属于其他用户。

市场状态

HTTP	error	触发条件
404	MARKET_NOT_FOUND	symbol 在 spot_markets 中不存在。
409	MARKET_HALTED	市场处于 halted 状态；不接受新订单。
410	MARKET_DELISTED	市场处于 delisted 状态；已终止。

下单 (POST /spot/orders)

HTTP	error	触发条件
400	invalid side	side 不在 sell 中。
400	invalid type	type 不在 market 中。
400	invalid tif	tif 不在 post_only 中。注意：仅接受小写。
400	quantity required for limit	limit 订单缺少 quantity。
400	quantity required for market sell	market 卖单缺少 quantity。
400	quote_quantity required for market buy	market 买单缺少 quote_quantity。
400	INVALID_TICK	price 不是市场 tick_size 的整数倍。
400	INVALID_LOT	quantity 不是市场 lot_size 的整数倍。
400	BELOW_MIN_NOTIONAL	price * quantity < min_notional。
400	INSUFFICIENT_BALANCE	订单所需锁定金额（卖单锁定基础资产，买单锁定报价资产）超过调用方的 available 余额。
400	POST_ONLY_REJECT	tif=post_only 订单在下单时将立即与订单簿撮合。
400	SELF_TRADE	新订单将与调用方自身的挂单发生撮合（DECLINE_TAKER 策略）。

订单管理

HTTP	error	触发条件
400	invalid id	路径参数 :id 不是有效的 UUID。
404	ORDER_NOT_FOUND	订单不存在、已处于终态，或属于其他用户。
404	WITHDRAWAL_NOT_FOUND	提币 id 不存在或属于其他用户。

撮合引擎可用性

HTTP	error	触发条件	处理建议
503	spot trading disabled	本服务器 SPOT_TRADING_ENABLED=false。	该环境的永久性限制。
503	ENGINE_BUSY	撮合引擎 mpsc 积压队列已满。	使用退避策略重试（200 / 400 / 800 ms）。
503	ENGINE_RESTARTING	恢复中。	等待几秒后重试。
503	TICKER_NOT_FOUND	对尚无记录的交易对调用 GET /spot/ticker/24hr?symbol=…。	首次成交后将自动解决。

划转 (POST /spot/transfer)

HTTP	error	触发条件
400	INVALID_DIRECTION	direction 不在 spot_to_perp 中。
400	AMOUNT_NON_POSITIVE	amount <= 0。
400	INSUFFICIENT_BALANCE	来源侧没有足够的可用 USDT。
400	UNSUPPORTED_TOKEN	MVP 阶段仅支持 USDT。

提币 (POST /spot/withdraw/request)

HTTP	error	触发条件
400	AMOUNT_NON_POSITIVE	amount <= 0。
400	INSUFFICIENT_BALANCE	请求代币的 available < amount。
400	UNSUPPORTED_TOKEN	该代币不在现货钱包支持列表中（当前仅支持 DF）。
503	SIGNER_UNAVAILABLE	后端签名器（或其 KMS）无法访问。为暂时性错误。

管理员接口 (/admin/spot/*)

HTTP	error	触发条件
400	INVALID_STATUS	status 不在 delisted 中。
400	AMOUNT_NON_POSITIVE	增发金额 <= 0。
404	DISABLED	在 TESTNET_ONLY != true 时调用 POST /admin/spot/balances/credit。
409	MARKET_EXISTS	创建的市场 id 已存在。
500	DB_ERROR	管理员写操作期间发生 Postgres 错误。

服务端故障

HTTP	error	触发条件
500	DB_ERROR	写操作期间发生意外 Postgres 错误。请排查日志。
500	(HTML 响应体)	请求任务发生 panic。请捕获请求信息并上报。