跳到主要内容

错误代码

接口错误码 (/fapi)​

当 /fapi 接口拒绝请求时，响应体结构如下:

{
  "code": -1121,
  "msg": "Invalid symbol: XYZUSDT"
}

大多数错误以 HTTP 状态码 400 返回；-2013（订单不存在）可能以 404 返回，-1000/-1001（内部错误）以 500 返回。

当前在用的错误码如下:

10xx — 常规问题​

错误代码错误名称错误描述 / 原因
-1000UNKNOWN处理请求时发生未知错误（例如内部存储错误）。
-1001DISCONNECTED内部错误，无法处理请求，请重试。
-1013FILTER_FAILURE订单被交易对过滤器拒绝。消息中会指明失败的过滤器: Filter failure: LOT_SIZE（数量低于最小下单量，或取整后低于最小下单量）、Filter failure: MIN_NOTIONAL（订单名义价值低于该交易对最小值；仅减仓订单豁免）、Filter failure: MAX_NOTIONAL（订单名义价值高于该交易对最大值）。各交易对的过滤器取值发布在 GET /fapi/v1/exchangeInfo 响应的 filters 数组中。

11xx — 请求参数问题​

错误代码错误名称错误描述 / 原因
-1100ILLEGAL_CHARS / BAD_VALUE参数值格式非法: 无效的 quantity、price、stopPrice、orderId 或 goodTillDate；数值非正数；newClientOrderId 超过 36 字符或包含非法字符；查询窗口超过 7 天。
-1102MANDATORY_PARAM_EMPTY_OR_MALFORMED必填参数未发送: 如 quantity、LIMIT 订单的 price、撤单/查询时的 orderId/origClientOrderId、timeInForce=GTD 时的 goodTillDate。在普通（非算法）订单上发送 timeInForce=GTD 也会返回此错误（不支持）。
-1106PARAM_NOT_REQUIRED发送了不需要或与其他参数冲突的参数: closePosition 与 reduceOnly 或 quantity 同时出现，或在 STOP_MARKET / TAKE_PROFIT_MARKET 之外的订单类型上使用 closePosition。
-1120BAD_INTERVAL无效的 K 线间隔或统计周期。
-1121BAD_SYMBOL无效或未知的交易对。
-1125INVALID_LISTEN_KEY该 listenKey 不存在（已过期或从未创建）。请通过 POST /fapi/v1/listenKey 重新申请。
-1128OPTIONAL_PARAMS_BAD_COMBO可选参数组合或取值无效，例如 marginType 不是 CROSSED / ISOLATED。
-1130INVALID_PARAMETER参数数据无效: 未知的 side、type、algoType，或 positionSide 不是 BOTH。

20xx — 订单处理问题​

错误代码错误名称错误描述 / 原因
-2010NEW_ORDER_REJECTED新订单被拒绝，例如 GTX（post-only）订单会立即成交吃单。
-2011CANCEL_REJECTED撤单被拒绝: 订单未知，或订单已处于终态。
-2013NO_SUCH_ORDER订单不存在（或无法修改）。
-2014DUPLICATE_CLIENT_ORDER_ID重复的 newClientOrderId — 另一个活跃订单已使用该 id。
-2019MARGIN_NOT_SUFFICIENT可用余额不足以支付所需保证金。
-2021ORDER_WOULD_IMMEDIATELY_TRIGGER条件订单按当前标记价格会被立即触发。
-2022REDUCE_ONLY_REJECT仅减仓订单被拒绝: 没有可减的反向持仓。

40xx — 账户配置问题​

错误代码错误名称错误描述 / 原因
-4028INVALID_LEVERAGE杠杆无效: 低于 1 或高于该交易对的最大杠杆。
-4046MARGIN_TYPE_NOT_SUPPORTED不支持逐仓 — 交易所仅运行在全仓模式。
-4059POSITION_MODE_NOT_SUPPORTED不支持双向持仓模式（dualSidePosition=true）— 交易所仅运行在单向持仓模式。

鉴权错误​

鉴权失败不使用上面的 {code, msg} 格式。它们在接口执行之前就被鉴权中间件拒绝，返回 HTTP 401（或 403）状态码及标准 API 响应信封:

{
  "success": false,
  "data": null,
  "error": {
    "code": "SIGNATURE_INVALID",
    "message": "Timestamp outside recv window"
  },
  "timestamp": 1711000000
}
HTTP 状态码错误码原因
401SIGNATURE_INVALIDHMAC 签名校验失败: 缺少 signature 或 timestamp 参数、签名无效、或 timestamp 超出相对服务器时间固定的 ±60,000 毫秒窗口。
401INVALID_API_KEYX-MBX-APIKEY 请求头不匹配任何已知 API key。
401API_KEY_DISABLEDAPI key 存在但已被禁用。
403IP_NOT_ALLOWED客户端 IP 不在该 API key 的 IP 白名单中。

注意: 时间戳和签名问题按上述方式返回 401 SIGNATURE_INVALID — 本 API 不存在 -1021 / -1022 风格的错误码。