错误码

存在三种错误信封，按你调用的接口面选择对应的表。

FAPI 业务错误（Binance 信封）

HTTP/1.1 400 Bad Request
content-type: application/json

{ "code": -2019, "msg": "Margin is insufficient." }

Code	HTTP	名称	触发条件
-1000	500	UNKNOWN	未分类错误（如 fundingFeeHistory 的数据库错误）
-1001	500	DISCONNECTED	内部服务错误 / 分片转发失败
-1003	429	TOO_MANY_REQUESTS	超出请求权重或下单计数上限，见限流；响应头带当前计数
-1013	400	INVALID_QUANTITY	quantity < lot_size，或名义额超出 [min_order_size_usd, max_order_size_usd]
-1021	400	INVALID_TIMESTAMP	timestamp 超出 ±60 秒窗口
-1100	400	ILLEGAL_CHARS	UUID / 数量 / 价格无法解析；clientOrderId 含非法字符；algo 查询窗口超过 7 天
-1102	400	MANDATORY_PARAM_EMPTY_OR_MALFORMED	缺必填参数；修改单 side 不一致；不支持的 timeInForce；batchOrders 非法
-1106	400	PARAMETER_NOT_REQUIRED	quantity 与 quoteOrderQty 同时传；closePosition 冲突
-1120	400	INVALID_INTERVAL	K 线 interval / futures-data period 非法
-1121	400	INVALID_SYMBOL	symbol 不在当前部署的市场配置中
-1125	404	INVALID_LISTEN_KEY	PUT /fapi/v1/listenKey 时没有活跃 listenKey
-1130	400	INVALID_DATA_FOR_PARAMETER	side / type / algoType / positionSide 不可识别
-2010	400	NEW_ORDER_REJECTED	GTX 会立即成交；超出 OI 上限；触发单数量达上限
-2011	400	UNKNOWN_ORDER	撤单 / 修改时引擎找不到该订单（不会伪造 CANCELED）
-2013	404	NO_SUCH_ORDER	订单不存在 / 不可修改 / 非活跃
-2014	400	API_KEY_FORMAT（复用）	活跃订单中 newClientOrderId 重复
-2019	400	MARGIN_INSUFFICIENT	可用余额不足以冻结保证金
-2021	400	ORDER_WOULD_TRIGGER_IMMEDIATELY	触发条件已满足
-2022	400	REDUCEONLY_REJECT	reduceOnly 但无反向持仓
-4028	400	INVALID_LEVERAGE	杠杆超出 [1, 市场上限]
-4046	400	NO_NEED_TO_CHANGE_MARGIN_TYPE（复用）	FAPI 上传 marginType=ISOLATED
-4059	400	NO_NEED_TO_CHANGE_POSITION_SIDE（复用）	dualSidePosition=true

FAPI 鉴权错误（Sparky 信封）

Key 与签名错误由鉴权中间件返回，使用 Sparky 的 ApiResponse 信封而非 Binance 信封。多数客户端只需关注 HTTP 状态码。

HTTP/1.1 401 Unauthorized
content-type: application/json

{ "success": false, "data": null, "error": { "code": "SIGNATURE_INVALID", "message": "..." }, "timestamp": 1714261234 }

error.code	HTTP	触发条件
INVALID_API_KEY	401	当前部署找不到 X-MBX-APIKEY
API_KEY_DISABLED	401	Key status != active
IP_NOT_ALLOWED	403	客户端 IP 不在白名单
SIGNATURE_INVALID	401	HMAC 不匹配、缺 timestamp 或时间戳越界

原生 API 错误（/api/v1/*）

{ "error": "Insufficient available balance", "code": "INSUFFICIENT_BALANCE" }

部分 handler 使用 { "success": false, "error": { "code", "message" } } 信封；请先看状态码。

Code	含义
INVALID_ADDRESS	钱包地址格式错误
TIMESTAMP_EXPIRED	登录 / EIP-712 时间戳超出 ±5 分钟
USER_NOT_FOUND	先调用 nonce 接口
SIGNATURE_INVALID、SIGNATURE_FORMAT_INVALID	EIP-712 签名失败 / 非 0x 开头
INVALID_TOKEN	JWT 缺失 / 过期
LIMIT_REACHED、INVALID_IP	API Key 创建限制
INVALID_SYMBOL、INVALID_LEVERAGE、INVALID_AMOUNT、PRICE_REQUIRED	订单校验
SLIPPAGE_EXCEEDED	市价单模拟滑点超过 max_slippage
INSUFFICIENT_BALANCE	可用余额不足
OI_CAP_EXCEEDED	订单将超出该市场单侧 OI 上限（消息含 current、cap、requested_delta）
ORDER_NOT_FOUND、ORDER_NOT_OWNED、ORDER_NOT_CANCELLABLE	订单查询 / 撤单
HAS_OPEN_ORDERS、HAS_OPEN_POSITIONS、INVALID_MARGIN_MODE	切换保证金模式前置条件
INVALID_MARKET、ERR_INVALID_PERIOD、ERR_NO_DATA、CIRCUIT_OPEN、PRICE_DATA_UNAVAILABLE	行情端点

推荐返佣的错误码见推荐返佣概述。

常见坑

• 只有 POST/PUT 报 SIGNATURE_INVALID — 你只对查询串签了名，没有追加原始 JSON body（或对 body 做了 URL-encode）。见 签名。
• -1021 — 用 GET /fapi/v1/time 校时；窗口 60 秒且 recvWindow 无法加宽，未来时间戳同样失败。
• 别处能用的 Key 报 INVALID_API_KEY — Key 按链隔离，你连的是另一条链的部署。
• 撤单返回 -2011 — 订单已成交 / 已撤。视为完成，再用 GET /fapi/v1/order 对账。
• 浮点尾数导致 -1013 — 非 lot 整数倍的数量会被向下取整，但不足一个 lot 会被拒；发送前先取整。