错误码

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

鉴权与权限

HTTP	error	触发条件
401	(响应体为空)	JWT 缺失 / 无效、HMAC 签名缺失 / 错误，或 timestamp 超出服务器时间 ±60000 ms 范围。
403	API Key permission denied: transfers not allowed	API Key 调用方访问了 POST /spot/transfer（仅限 JWT）。
403	API Key permission denied: withdraws not allowed	API Key 调用方访问了 POST /spot/withdraw/request（仅限 JWT）。
403	FORBIDDEN	撤销属于其他用户的订单。提币不同：查询其他用户的提币 id 返回 404 not found，绝不会返回 403。

市场状态

HTTP	error	触发条件
404	MARKET_NOT_FOUND	symbol 在 spot_markets 中不存在。
404	TICKER_NOT_FOUND	对尚无 ticker 记录的交易对调用 GET /spot/ticker/24hr?symbol=…。首次成交后将自动解决。
409	MARKET_HALTED	市场处于 halted 状态；不接受新订单。
410	MARKET_DELISTED	市场处于 delisted 状态；已终止。
400	market.status invalid	市场记录的 status 值无法识别。

下单 (POST /spot/orders)

HTTP	error	触发条件
400	invalid side	side 不在 sell 中。
400	invalid type	type 不在 market 中。
400	invalid tif	tif 不在 post_only 中。注意：仅接受小写。
400	price required for limit	limit 订单缺少 price。
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	not found	提币 id 不存在或属于其他用户。

撮合引擎可用性

HTTP	error	触发条件	处理建议
503	spot trading disabled	本服务器 SPOT_TRADING_ENABLED=false。	该环境的永久性限制。
503	ENGINE_BUSY	撮合引擎 mpsc 积压队列已满——仅 POST /spot/orders 与 GET /spot/depth。	使用退避策略重试（200 / 400 / 800 ms）。
503	ENGINE_RESTARTING	恢复中——仅 POST /spot/orders 与 GET /spot/depth。	等待几秒后重试。

撤单接口上的引擎队列溢出表现不同：DELETE /spot/orders/:id 映射为 500 DB_ERROR；DELETE /spot/orders（全部撤单）返回 200 且 canceled 数组为空——与没有挂单的情形无法区分。

划转 (POST /spot/transfer)

HTTP	error	触发条件
400	invalid direction: <direction>	direction 不在 spot_to_perp 中。
400	amount must be positive	amount <= 0。
400	insufficient balance	来源侧没有足够的可用 USDT。
400	unsupported token: <token>	MVP 阶段仅支持 USDT。

提币 (POST /spot/withdraw/request)

HTTP	error	触发条件
400	unsupported token: <token>	该代币不在现货钱包支持列表中（当前仅支持 DF）。
400	amount below minimum <min>	amount 低于服务器配置的最小值。不存在单独的非正数校验——零 / 负数金额同样在此处失败。
400	insufficient balance	请求代币的 available < amount。
409	you have a pending withdrawal — submit it on-chain or wait for it to expire before signing a new one	已存在 nonce 不小于合约当前 nonce 的 signed 提币。
409	withdrawal slot conflict — try again in a moment	(user, chain, nonce) 槽位被一条未过期的记录占用。
500	chain query failed	读取金库链上 release nonce 失败。
500	signer unavailable	后端提币签名器初始化失败。
500	sign failed	EIP-712 签名失败。
503	spot blockchain not initialized	BSC 区块链服务未运行。

管理员接口 (/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	internal error / internal	钱包侧接口（/spot/transfer、/spot/withdraw*、/spot/withdrawals*）发生意外 Postgres 错误。这些接口绝不会返回 DB_ERROR。
500	(HTML 响应体)	请求任务发生 panic。请捕获请求信息并上报。