币安 API 错误码采用 负整数编码，范围从 -1000 到 -2099，分为 通用错误 (-1000 ~ -1199)、请求错误 (-1100 ~ -1199)、限频/风控 (-1003/-1013)、订单错误 (-2010 ~ -2099) 四大类。本文整理了 80+ 个生产环境实际遇到的错误码及处理方案，配合 Python 错误处理中间件代码。未开通 API 的读者请先到 币安官网 完成 KYC，新用户可通过 免费注册。
一、错误响应结构
币安 API 所有错误响应格式统一：
{
"code": -1021,
"msg": "Timestamp for this request is outside of the recvWindow."
}
HTTP 状态码通常是 400（业务错误）或 403/429/418（网关错误）。
二、通用错误（-1000 至 -1099）
| 错误码 | 消息 | 含义 | 处理方案 |
|---|---|---|---|
| -1000 | UNKNOWN | 未知错误 | 重试；若持续联系客服 |
| -1001 | DISCONNECTED | 服务器内部断开 | 等 5s 重试 |
| -1002 | UNAUTHORIZED | 未鉴权 | 检查 X-MBX-APIKEY 头 |
| -1003 | TOO_MANY_REQUESTS | 超出限频 | 按 Retry-After 秒数等待 |
| -1006 | UNEXPECTED_RESP | 响应异常 | 重试 |
| -1007 | TIMEOUT | 请求超时 | 增加 recvWindow |
| -1014 | UNKNOWN_ORDER_COMPOSITION | 不支持的组合单 | 检查订单类型 |
| -1015 | TOO_MANY_ORDERS | 订单数超限 | 撤部分未成交单 |
| -1016 | SERVICE_SHUTTING_DOWN | 服务停机 | 等恢复 |
| -1020 | UNSUPPORTED_OPERATION | 不支持的操作 | 查文档 |
| -1021 | INVALID_TIMESTAMP | 时间戳偏差 | 同步 NTP 或加大 recvWindow |
| -1022 | INVALID_SIGNATURE | 签名无效 | 检查签名算法 |
重点错误详解
-1003 TOO_MANY_REQUESTS：
{"code": -1003, "msg": "Too many requests; current limit is 6000 request weight per 1 MINUTE. Please use WebSocket Streams for live updates to avoid polling the API."}
处理：
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 60))
time.sleep(retry_after)
# 之后重试
-1021 INVALID_TIMESTAMP：
{"code": -1021, "msg": "Timestamp for this request is outside of the recvWindow."}
处理：
# 方案 1：同步服务器时间差
server_time = requests.get("https://api.binance.com/api/v3/time").json()["serverTime"]
local_time = int(time.time() * 1000)
offset = server_time - local_time # 保存并在每次签名时加上
# 方案 2：扩大 recvWindow（最大 60000）
params["recvWindow"] = 10000
-1022 INVALID_SIGNATURE：
{"code": -1022, "msg": "Signature for this request is not valid."}
常见原因：
- 签名字符串和请求字符串参数顺序不一致
- 数字参数加了引号
- Secret Key 被截断或有空格
- URL 编码方式不同
三、参数错误（-1100 至 -1199）
| 错误码 | 消息 | 含义 | 处理 |
|---|---|---|---|
| -1100 | ILLEGAL_CHARS | 参数含非法字符 | 清理输入 |
| -1101 | TOO_MANY_PARAMETERS | 参数过多 | 精简参数 |
| -1102 | MANDATORY_PARAM_EMPTY_OR_MALFORMED | 必填参数缺失 | 检查 API 文档 |
| -1103 | UNKNOWN_PARAM | 未知参数 | 移除多余字段 |
| -1104 | UNREAD_PARAMETERS | 参数未使用 | 删除冗余参数 |
| -1105 | PARAM_EMPTY | 参数为空 | 填入有效值 |
| -1106 | PARAM_NOT_REQUIRED | 不该传的参数 | 移除 |
| -1111 | BAD_PRECISION | 精度错误 | 符合 LOT_SIZE / PRICE_FILTER |
| -1112 | NO_DEPTH | 订单簿为空 | 等待行情恢复 |
| -1114 | TIF_NOT_REQUIRED | TIF 不适用 | 市价单不要传 timeInForce |
| -1115 | INVALID_TIF | TIF 无效 | 使用 GTC / IOC / FOK |
| -1116 | INVALID_ORDER_TYPE | 订单类型无效 | 检查支持的类型 |
| -1117 | INVALID_SIDE | side 无效 | BUY 或 SELL |
| -1118 | EMPTY_NEW_CL_ORD_ID | 客户端订单 ID 为空 | 提供 newClientOrderId 或省略 |
| -1119 | EMPTY_ORG_CL_ORD_ID | 原订单 ID 为空 | 撤单/查询时提供 orderId |
| -1120 | BAD_INTERVAL | K 线间隔无效 | 1m/5m/15m/1h/4h/1d 等 |
| -1121 | BAD_SYMBOL | 交易对无效 | 调用 exchangeInfo 验证 |
| -1125 | INVALID_LISTEN_KEY | listenKey 无效 | 重新调用 userDataStream |
| -1127 | MORE_THAN_XX_HOURS | 查询时间跨度超限 | 改用多次查询 |
| -1128 | OPTIONAL_PARAMS_BAD_COMBO | 可选参数组合错 | 查文档看互斥 |
| -1130 | INVALID_PARAMETER | 参数值非法 | 修正值范围 |
| -1131 | INVALID_JSON | JSON 格式错 | 验证 JSON |
重点详解
-1111 BAD_PRECISION（超高频错误）：
Filter failure: LOT_SIZE
原因：数量或价格不符合该交易对的 stepSize / tickSize。
# 正确做法：查询交易规则后四舍五入
import math
def get_filters(symbol: str) -> dict:
r = requests.get("https://api.binance.com/api/v3/exchangeInfo",
params={"symbol": symbol}).json()
return {f["filterType"]: f for f in r["symbols"][0]["filters"]}
def round_step(value: float, step: float) -> float:
return math.floor(value / step) * step
filters = get_filters("BTCUSDT")
step_size = float(filters["LOT_SIZE"]["stepSize"]) # 0.00001
tick_size = float(filters["PRICE_FILTER"]["tickSize"]) # 0.01
min_notional = float(filters["NOTIONAL"]["minNotional"]) # 5.0
# 下单前规范化
quantity = round_step(0.0015789, step_size) # → 0.00157
price = round_step(60123.4567, tick_size) # → 60123.45
四、过滤器失败（-1013）
-1013 INVALID_MESSAGE 配合不同 filter 给出具体原因：
| Filter 类型 | 含义 | 处理 |
|---|---|---|
| PRICE_FILTER | 价格不符合 tickSize | 按 tickSize 取整 |
| LOT_SIZE | 数量不符合 stepSize | 按 stepSize 取整 |
| MIN_NOTIONAL | 订单总额太低（<5 USDT） | 提升数量 |
| NOTIONAL | 名义价值不符 | 同 MIN_NOTIONAL |
| PERCENT_PRICE | 价格偏离过大 | 靠近市价 |
| MARKET_LOT_SIZE | 市价单数量不符 | 符合市价单规则 |
| MAX_NUM_ORDERS | 单交易对挂单数超限 | 撤单后再下 |
| MAX_NUM_ALGO_ORDERS | 算法单超限 | 撤销部分止损止盈 |
五、订单错误（-2010 至 -2099）
| 错误码 | 消息 | 含义 | 处理 |
|---|---|---|---|
| -2010 | NEW_ORDER_REJECTED | 下单被拒 | 看具体 msg |
| -2011 | CANCEL_REJECTED | 撤单被拒 | 订单可能已成交 |
| -2013 | NO_SUCH_ORDER | 订单不存在 | 检查 orderId |
| -2014 | BAD_API_KEY_FMT | Key 格式错 | 检查 64 位 |
| -2015 | REJECTED_MBX_KEY | Key / IP / 权限不对 | 检查白名单和权限 |
| -2016 | NO_TRADING_WINDOW | 无交易窗口 | 交易对暂停 |
| -2018 | BALANCE_NOT_SUFFICIENT | 余额不足 | 充值或减少数量 |
| -2019 | MARGIN_NOT_SUFFICIENT | 保证金不足 | 降杠杆或加保证金 |
| -2020 | UNABLE_TO_FILL | 无法成交 | 限价单价格调整 |
| -2021 | ORDER_WOULD_IMMEDIATELY_TRIGGER | 订单会立即触发 | 调整止损止盈价 |
| -2022 | REDUCE_ONLY_REJECT | 只减仓被拒 | 检查持仓方向 |
| -2023 | USER_IN_LIQUIDATION | 用户强平中 | 等强平结束 |
| -2024 | POSITION_NOT_SUFFICIENT | 持仓不足 | 无法平仓这么多 |
| -2025 | MAX_OPEN_ORDER_EXCEEDED | 挂单数超限 | 撤部分旧单 |
| -2026 | REDUCE_ONLY_ORDER_TYPE_NOT_SUPPORTED | 类型不支持只减仓 | 改市价或限价 |
| -2027 | MAX_LEVERAGE_RATIO | 杠杆超限 | 降低杠杆 |
| -2028 | MIN_LEVERAGE_RATIO | 杠杆过低 | 提升 |
重点详解
-2010 NEW_ORDER_REJECTED（最常见）：
msg 字段会给出具体原因：
"Account has insufficient balance for requested action"→ 余额不足"Order would immediately match and take"→ 限价单会立即吃单（LIMIT_MAKER 模式下）"Filter failure: LOT_SIZE"→ 数量不符合步长"Filter failure: PERCENT_PRICE"→ 价格偏离过大
def place_order_safely(symbol, side, qty, price):
try:
return client.create_order(
symbol=symbol, side=side, type="LIMIT",
timeInForce="GTC", quantity=qty, price=price
)
except BinanceAPIException as e:
if e.code == -2010:
if "insufficient balance" in e.message:
return {"error": "余额不足"}
if "Filter failure: LOT_SIZE" in e.message:
return {"error": "数量精度错，需按 stepSize 取整"}
raise
-2015 REJECTED_MBX_KEY：
三种子原因（从错误消息里推断）：
- API Key 格式错：检查 64 位长度
- IP 不在白名单：登录币安更新
- 权限未启用：例如调用 /fapi/ 但未勾 Enable Futures
六、风控相关错误
| 错误码 | 消息 | 含义 | 处理 |
|---|---|---|---|
| -4001 | PRICE_LESS_THAN_ZERO | 价格负数 | 检查参数 |
| -4002 | PRICE_GREATER_THAN_MAX_PRICE | 价格超上限 | 降低价格 |
| -4003 | QTY_LESS_THAN_ZERO | 数量负数 | 改为正数 |
| -4004 | QTY_LESS_THAN_MIN_QTY | 数量低于最小值 | 参考 LOT_SIZE |
| -4005 | QTY_GREATER_THAN_MAX_QTY | 数量超上限 | 分批下单 |
| -4006 | STOP_PRICE_LESS_THAN_ZERO | 止损价负数 | 改正 |
| -4164 | MIN_NOTIONAL | 名义金额不足 5 USDT | 增加数量 |
| -5021 | FOK_ORDER_REJECT | FOK 订单被拒 | 流动性不足，换 GTC |
| -5022 | GTX_ORDER_REJECT | GTX（Post Only）被拒 | 市价已改变，价格不再是挂单 |
七、统一错误处理中间件（Python）
import time
import requests
from typing import Optional
class BinanceAPIError(Exception):
def __init__(self, code: int, msg: str, raw: dict):
self.code = code
self.msg = msg
self.raw = raw
super().__init__(f"Binance {code}: {msg}")
def handle_response(response: requests.Response) -> dict:
data = response.json()
if "code" in data and data["code"] < 0:
raise BinanceAPIError(data["code"], data.get("msg", ""), data)
return data
def request_with_recovery(method, url, **kwargs) -> Optional[dict]:
for attempt in range(5):
try:
r = requests.request(method, url, **kwargs)
if r.status_code == 429:
retry_after = int(r.headers.get("Retry-After", 60))
print(f"限频，等待 {retry_after}s")
time.sleep(retry_after)
continue
if r.status_code == 418:
raise SystemExit("IP 被封，程序终止")
data = handle_response(r)
return data
except BinanceAPIError as e:
if e.code == -1021:
print("时间戳偏差，重新同步")
# 同步时间后重试
continue
if e.code in (-1001, -1006, -1007):
wait = 2 ** attempt
print(f"临时错误 {e.code}，{wait}s 后重试")
time.sleep(wait)
continue
# 不可重试的业务错误直接抛
raise
return None
八、常见问题 FAQ
Q1: 错误码 -1021 反复出现怎么办？
A: 系统时钟问题。Linux 启用 chronyd：
sudo systemctl enable chronyd
sudo chronyc sources -v # 验证同步源
Windows 从控制面板 → 日期时间 → Internet 时间 → 同步 time.windows.com。
Q2: 看到 -1015 TOO_MANY_ORDERS 是什么原因？
A: 单交易对的 未成交挂单 数超过 200（Spot）或 MAX_NUM_ORDERS filter 设定的上限。撤销部分远价格挂单即可。
Q3: -2015 排查完权限和 IP 都没错，还是报错？
A: 检查是否把 Spot Key 用到了 Futures 域名（fapi.binance.com），或反之。Spot 和 Futures 需要的权限位不同，同一密钥如果没勾 Enable Futures，无法用于合约接口。
Q4: 如何在日志中记录所有错误码？
A: 封装一个中间件层，按错误码统计：
from collections import Counter
error_counter = Counter()
def log_error(code: int):
error_counter[code] += 1
if error_counter[code] > 100:
alert(f"错误 {code} 发生 {error_counter[code]} 次，可能有系统问题")
Q5: -1013 和 -2010 有什么区别？
A: -1013 是 filter 错误（参数不符合交易规则），-2010 是订单被拒绝（业务层拒绝，原因在 msg 中）。-1013 通常在客户端预先计算就能避免，-2010 更多依赖实时市场状态（余额、滑点、风控）。
看完错误码清单，回到 分类导航 查看「API接入」分类其它技术专题。