对接交易接口时，最心烦的不是策略跑得不顺，而是面对一串冷冰冰的 code 却无从下手。下文把币安 Spot REST API 所有常见错误代码按大类拆开，告诉你“它到底在说什么”，并给出直接可落地的修复思路。收藏这一篇，就能省下无数抓耳挠腮的 Debug 时间。为什么你需要这份清单
- 定位更快：一看到
-1003就知道是“请求过多”，优先检视速率与 IP，而不是去改参数。 - 减少试错：
-1111精度过高时，立刻把价格调整至币安的最小跳动值（tickSize），不必乱改数量。 - 合规布线：
-2015粗暴拒绝往往只是 IP 白名单没配，GitHub Actions 一上墙就能跑通。
关键词：币安接口错误、API 返回码、接口调试、交易对错误、签名失败、请求限制。
10xx 服务器或网络类错误
| 代码 | 典型信息 | 含义与快速解 |
|---|---|---|
| -1000 | 未知错误 | 99% 重试即好；若持续出现👉 看这里 做链路自检。 |
| -1001 | 连接断开 | 内部网关抖动，指数退避重连。 |
| -1002 | 未授权 | API Key 没启用现货权限，或 URL 拼错用了 /fapi 却传了 /api。 |
| -1003 | 请求过多 | IP/KEY 被限速：短时降至 1/10 QPS，长期建议切 WebSocket 流。 |
| -1006 | 非常规响应 | 刚好遇到系统更新，5 秒内重发即可。 |
| -1007 | 超时 | 下单结果未知，必须拿 orderId 轮询确认状态。 |
| -1008 | SERVER_BUSY | 官网公告频道常提示“现货系统过载”，等 3–5 分钟即可。 |
| -1013 | 消息无效 | 多半是过滤器拒绝，需参见章节《订单未能通过过滤器》自查。 |
| -1015 | 订单太多 | 当日挂单>200000 单，清理历史挂单或升级 VIP 档。 |
| -1016 | 服务器下线 | 切备用域名 api1/api2/binance.com。 |
| -1021 | 时间同步问题 | recvWindow 默认 5000 ms 仍超时？把服务器同步到 NTP。 |
| -1022 | 签名不正确 | 排查顺序：Secret 是否正确 → 是否 URL encode → 时间戳是否秒级。 |
11xx 请求参数类错误
高频场景速查
-1101参数太多
GET 只带必要字段，多余的合法但不读的参数需删除——多一个&recvWindow=也会被拒。-1102缺少必填参数
Buy Market Order 忘带quoteOrderQty会直接掉坑里。-1111精度过高
对 BTC/USDT 来说 price 小数多于 2 位就触发，记得读/exchangeInfo的tickSize。-1121无效的交易对
常是用了下划线"BTC_USDT"，Spot 路径要求"BTCUSDT"。-1155SBE 未开启
精简二进制编码默认关闭，如非高频行情场景，删掉X-MBX-SBE头。
交易引擎核心返回（-2010、-2011、-2013）
当 code = -2010/-2011 时，真正的错误藏在了 msg 字段。
典型 msg 对照表
| 参考文字 | 实用建议 |
|---|---|
| Account has insufficient balance | 现货账户有余额，但可能在杠杆仓；提前 POST /api/v3/account 核对可用。 |
| Market orders are not supported | 该币对仅支持限价；改用 LIMIT_MAKER 或非 MARKET 的 orderType. |
| Order would trigger immediately | 止损价距离现价太近，稍微拉大触发价差。 |
| This symbol is restricted for this account | 检查 permissions 字段是否包含 SPOT。若账户只有逐仓杠杆权限，现货单会直接拒绝。 |
过滤器拒绝汇总
过滤器错误统一格式：Filter failure: XXX。直接用关键词搜索，立刻知道改什么。
- PRICE_FILTER：price 必须满足
minPrice ≤ price ≤ maxPrice并且是tickSize的整数倍。 - LOT_SIZE：
quantity同理。 - MIN_NOTIONAL：price * qty ≥ minNotional，市价单用
quoteOrderQty时注意。 - MAX_NUM_ORDERS：单个交易对同时挂单≤该值，机器人扫货前先把历史挂单清理掉。
- TRAILING_DELTA：介于 minTrailingAboveDelta 与 maxTrailingAboveDelta 之间。
如果我们把所有交易对的过滤器信息打表会给文章加载造成压力，👉 点此获取实时过滤器数据 比手动维护更可靠。
FAQ：5 个高频疑问一次说清
Q1：我拿到了 -1003，但我的程序根本没那么高的频率？
A：币安对 IP 与 Key 双重限速。即使每个请求权重极低（1），10 秒内拉盘口 120 次仍会触发。最佳实践：行情改用监听流 (@depth,@ticker)，下单接口只在成交事件回调里触发。
Q2：对时工具提示已 NTP 同步，仍报 -1021？
A：系统调用不一定是 UTC。在 Python 中换 time.time() → int(time.time()*1000) 并保持服务器为 UTC 时区，基本能解决。
Q3：-2013 导致撤单成功却没有返回，到底算成没撤？
A：遇见网络闪断即可产生“客户端收到 2013，服务器实际已撤”的情况。后续 30 秒内再次用同一 orderId REST 轮询即可拿到最终状态，切勿盲目重下。
Q4：-2026 订单被归档还能查得到吗？
A：90 天无成交的订单将转冷存储，REST 返回 -2026，但可通过 Binance App 导出历史报表，或申请 SFTP 下载。
Q5：想通过 SBE 把行情体积压缩 70%，却一直 -1155？
A：SBE 需要在 行情 WebSocket 专域 wss://stream.binance.com:9443 打开，且必须在登录帧中声明 schemaId，不要对 rest 端点加 X-MBX-SBE。
问题定位三步法（实战模板）
- 先核对
code，看属于“网络/签名”还是“业务拒绝”。 - 如果
-2010/-2011/-1013，直接提取msg关键词对照上文的速查表。 - 涉及到过滤器，就再读一次
/api/v3/exchangeInfo对应交易对，别拿 3 个月前的缓存当标准。
小结
本文按“错误大类 → 代码 → 典型场景 → 修复动作”四段式梳理了币安 Spot 接口最常踩的坑。只要在日志里看到这些数字，就能秒懂“错在哪、怎么改”。
下一步行动建议：把这份速查表放进你们的 Bot 注释或 README，每次代码发布后跑一次回归测试，提前捕获 -1003、-1022 这类环境/权限型错误，让交易策略专注于 Alpha，而不是 Debug。