首页 / 实战日志 / API 报错 -1013

币安 API 下单被 -1013 拒掉时先看 Filter failure 后面的过滤器名

-1013 是订单被过滤器挡在了 API 层,去看 msg 里冒号后面那个大写名字。

2026-10-01 发布 PromptDeck 撰 阅读约 8 分钟 约 2,400 字

下单接口返回 -1013,说明这笔请求在 API 这一层就被拒了,没有送到撮合引擎,订单也就没有挂上去。卡在哪一道检查,看返回里的 msg:写着 Filter failure: LOT_SIZE 这种格式时,冒号后面的大写名字就是没通过的过滤器。到这个交易对的过滤器规则里找同名的那一组,把数量或价格改进规则范围,再重新签名发出。

币安开发者文档现货 Errors 页给 -1013 的说明是这三行:

-1013 INVALID_MESSAGE
The request is rejected by the API. (i.e. The request didn't reach the Matching Engine.)
Potential error messages can be found in Filter Failures or Failures during order placement.

每个交易对挂着哪些过滤器、数值是多少,都在 /exchangeInfo 的返回里,每一组用 filterType 标明是哪种过滤器。排查前准备好这次发出去的完整参数(symbol、side、type、price、quantity),以及这个交易对过滤器规则的原文。文档示例里这些数值是带引号的字符串,比如 "stepSize": "0.00100000",脚本启动时读进来用,别抄成代码里的常数。返回码如果是 -1021,问题出在时间戳,和过滤器无关,按-1021 时间戳超出 recvWindow 的排查步骤去查。

1. 从 -1013 的 msg 认出是哪个过滤器拦的单 #

Errors 页的 Filter failures 表把消息原文和说明一一对应。下面这些和单笔订单的参数有关,要改的是订单本身:

还有一组消息说的是账户状态。MAX_NUM_ORDERS、MAX_NUM_ALGO_ORDERS、MAX_NUM_ICEBERG_ORDERS、MAX_NUM_ORDER_LISTS 表示这个交易对上的挂单、止盈止损单、冰山单或订单组已经太多;前面加了 EXCHANGE_ 的四条,按整个交易所计数。这时要处理的是挂单的数量,撤掉用不上的再发。Filters 页里的 algo 单指 STOP_LOSS、STOP_LOSS_LIMIT、TAKE_PROFIT、TAKE_PROFIT_LIMIT 四种,普通挂单上限 maxNumOrders 把 algo 单也算在内。同一笔订单改单次数超限,Errors 页的消息表里写作 Filter failure: MAX_NUM_ORDER_AMENDS,Filters 页写的是会收到 -2038,排查时两种写法都对照一下。

MAX_POSITION 的持仓按三项相加:基础资产的可用余额、冻结余额,再加上所有未成交买单的数量。持仓超过 maxPosition 时买单会被拒;新下的这笔买单会让持仓越过上限,也过不了。要继续买,先卖出一部分,或者撤掉挂着的买单。

2. 报 LOT_SIZE 时对照 minQty、maxQty 和 stepSize #

LOT_SIZE 管数量,检查对象是 quantity,冰山单的 icebergQty 也按这一组规则查。三个条件要同时成立:

quantity >= minQty
quantity <= maxQty
quantity % stepSize == 0

取模那一行要求数量正好是 stepSize 的整数倍。stepSize 为 0.001 时,0.003 和 0.125 能过,0.0031 过不了,因为 0.0031 ÷ 0.001 = 3.1,除不尽。

这一步用浮点数做,容易出问题。0.1、0.001 这类小数在二进制浮点数里存不精确,取模、相除之后会带出极小的尾数,数量看着对齐了,转成字符串发出去却多了一长串小数位。数量和价格改用十进制类型处理,Python 里是 decimal.Decimal,直接拿 /exchangeInfo 返回的字符串构造。

如果返回的不是 -1013,而是 -1111 BAD_PRECISION,原文 "Parameter '%s' has too much precision.",指某个参数的小数位太多。把发出去的 quantity、price 字符串直接打印出来,和 stepSize、tickSize 的位数对照。

3. 限价单被 PRICE_FILTER 或 PERCENT_PRICE 拦下时怎么改价格 #

PRICE_FILTER 有 minPrice、maxPrice、tickSize 三项,检查对象是 price,止损类订单的 stopPrice 也要过这一关。三项里哪一项设成 0,那一项规则就不生效;生效的几项要满足:

price >= minPrice
price <= maxPrice
price % tickSize == 0

tickSize 为 0.01 时,3,217.45 能过,3,217.453 过不了。往哪边对齐由你定:买单价格向下取更保守,向上取更容易成交;卖单反过来。

PERCENT_PRICE 不设固定上下限,看的是价格离此前成交均价有多远。均价按这个顺序取:交易对有非空的参考价(reference price)就用参考价;没有的话,用之前 avgPriceMins 分钟内的成交量加权均价;avgPriceMins 为 0,就用最新成交价。限价要落在「均价 × multiplierDown」到「均价 × multiplierUp」之间。文档示例里 multiplierUp 是 1.3、multiplierDown 是 0.7,假如均价是 100,能挂的价格就在 70 到 130 之间(100 × 0.7 = 70,100 × 1.3 = 130)。

PERCENT_PRICE_BY_SIDE 把倍数按方向拆开,买单比 bidMultiplierUp 与 bidMultiplierDown,卖单比 askMultiplierUp 与 askMultiplierDown。挂一张离市价很远的限价单被拒时,先在 /exchangeInfo 的返回里确认这个交易对用的是哪一种,再按对应方向的倍数把价格往回拉。

4. NOTIONAL 和 MIN_NOTIONAL 都按价格乘数量检查 #

名义价值就是 price × quantity。Filters 页把这项检查写成两个独立的过滤器,字段各不相同:

某个交易对挂的是哪一个,看它过滤器规则里的 filterType。下单函数里两种都要认得,出现哪个就按哪个比,报错时也按 msg 里的名字去找对应那一组。

市价单不带价格,乘数量用的「price」和 PERCENT_PRICE 的均价取法相同:有非空参考价用参考价,没有就用之前 avgPriceMins 分钟的成交量加权均价,avgPriceMins 为 0 时用最新成交价。

5. 10 USDT 的买单按步长取整后为什么被 NOTIONAL 拒掉 #

下面这个交易对的规则是演示数字,不对应任何真实交易对:tickSize 0.01;LOT_SIZE 的 minQty 0.001、maxQty 100000、stepSize 0.001;NOTIONAL 的 minNotional 10、maxNotional 10000(LOT_SIZE 和 NOTIONAL 这几项取自 Filters 页的示例 JSON)。假设你想用 10 USDT 在 3,217.45 挂限价买单,数量由脚本按「预算 ÷ 价格」得出。

数量按 stepSize 向下取整没错,向上取会让花出去的钱超过预算。麻烦在取整之后:0.003 只值 9.65235 USDT,比 minNotional 少了 0.34765。预算本身就等于名义价值下限,只要原始数量不是 stepSize 的整数倍,向下取整后的名义价值就一定小于 10。在这个价格上,能过的最小数量是 0.004,要花 12.8698 USDT;手里只准备了 10 USDT,就只能加预算,或者放弃这一笔。

把这几步写进下单前的检查,报错前就能知道这笔单过不过得去:

# 演示数字;实盘从 /exchangeInfo 返回的字符串读取
from decimal import Decimal, ROUND_DOWN, ROUND_UP

step = Decimal("0.001")
min_qty = Decimal("0.001")
min_notional = Decimal("10")
price = Decimal("3217.45")
budget = Decimal("10")

qty = (budget / price / step).to_integral_value(rounding=ROUND_DOWN) * step
if qty < min_qty or price * qty < min_notional:
    need = (min_notional / price / step).to_integral_value(rounding=ROUND_UP) * step
    need = max(need, min_qty)
    print(f"预算不够:至少要买 {need},约 {price * need} USDT")
else:
    print(f"下单数量 {qty}")

按上面的输入,这段会打印「预算不够:至少要买 0.004,约 12.86980 USDT」。示意代码只比了 minQty 和 minNotional,maxQty、maxNotional 和价格那几项照同样的写法补上。让 AI 写下单函数时,把「过滤器数值从 /exchangeInfo 读、用 Decimal 取整、发单前先比名义价值下限」三条写进需求;改好的函数先拿到现货测试网上发几笔小单,确认返回和预期一致,测试网怎么接,见交易脚本接现货测试网的做法。

6. 市价单报 MARKET_LOT_SIZE 时看哪组数量规则 #

市价单的数量另有一组规则,filterType 是 MARKET_LOT_SIZE,字段名同样是 minQty、maxQty、stepSize,判断式也相同:

quantity >= minQty
quantity <= maxQty
quantity % stepSize == 0

市价单至少要过 MARKET_LOT_SIZE 这一组。LOT_SIZE 对市价单是否同时生效,文档没有明说,Errors 页倒是写了:用 quoteOrderQty 下的市价单,盘口流动性不足 LOT_SIZE 的最小数量时下不了单。所以两组的 minQty、maxQty、stepSize 都比一遍,改好的逻辑先在测试网上发几笔验证。收到 Filter failure: MARKET_LOT_SIZE,就到这一组取数重新取整;脚本拿它的 stepSize 当除数之前先判断一下,值为 0 就跳过按它取整这一步,别让代码除以零。名义价值那一关对市价单生不生效,回到第 4 节的表,看 applyToMarket、applyMinToMarket、applyMaxToMarket 三个开关。

7. U 本位合约下单报 -4164 MIN_NOTIONAL 等错误码怎么对照 #

U 本位合约文档的 Error Codes 页也列了 -1013 INVALID_MESSAGE,消息只有 "INVALID_MESSAGE." 一句。数量、价格、名义价值这几项检查,在页面上各有单独的编号:

-4164 在页面上有两种写法,除了写死 5.0 的那条,还有一条 "Order's notional must be no smaller than %s (unless you choose reduce only)",数字的位置是占位符 %s。从占位符的写法看,实际返回时会填进具体的数,脚本里别把 5 当成每个合约都一样的下限,以报错原文里的数为准。括号里的半句说的是选了 reduce only(只减仓)的订单不受这条限制。合约这边的 -1111 BAD_PRECISION 原文是 "Precision is over the maximum defined for this asset.",和现货一样,先查发出去的数量、价格字符串带了几位小数。

— PromptDeck, 2026-10-01