幣安 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接入」分類其它技術專題。