错误代码
10xx - 常规服务器或网络问题 (General Issues)
主要涉及网络连接、请求频率限制、鉴权和服务器内部错误。
| 错误代码 | 错误名称 | 错误描述 / 原因 |
|---|---|---|
| -1000 | UNKNOWN | 处理请求时发生未知错误。 |
| -1001 | DISCONNECTED | 内部错误，无法处理请求，请重试。 |
| -1002 | UNAUTHORIZED | 无权执行此请求。 |
| -1003 | TOO_MANY_REQUESTS | 请求权重过多/超限（可能导致IP被封）。建议使用 WebSocket。 |
| -1004 | DUPLICATE_IP | IP 地址已经在白名单中。 |
| -1005 | NO_SUCH_IP | 白名单上没有此 IP 地址。 |
| -1006 | UNEXPECTED_RESP | 从消息总线收到意外响应，执行状态未知。 |
| -1007 | TIMEOUT | 等待后端服务器响应超时，执行状态未知。 |
| -1008 | Request Throttled | 服务器过载或触发系统级保护机制被限流（仅减仓/平仓单豁免）。 |
| -1014 | UNKNOWN_ORDER_COMPOSITION | 不支持当前的下单参数组合。 |
| -1015 | TOO_MANY_ORDERS | 新订单数量超出限制。 |
| -1016 | SERVICE_SHUTTING_DOWN | 该服务不可用。 |
| -1020 | UNSUPPORTED_OPERATION | 不支持此操作。 |
| -1021 | INVALID_TIMESTAMP | 时间戳无效（在 recvWindow 之外，或比服务器时间提前超 1000ms）。 |
| -1022 | INVALID_SIGNATURE | 请求签名无效。 |
| -1023 | START_TIME_GREATER_THAN_END_TIME | 参数中的开始时间在结束时间之后。 |
| -1099 | NOT_FOUND | 未找到、未进行身份验证或未授权。 |
11xx - 请求参数问题 (Request Issues)
主要涉及 API 接口传参时的格式、类型、缺失或范围错误。
| 错误代码 | 错误名称 | 错误描述 / 原因 |
|---|---|---|
| -1100 | ILLEGAL_CHARS | 参数中发现非法字符。 |
| -1101 | TOO_MANY_PARAMETERS | 参数过多或检测到重复的参数值。 |
| -1102 | MANDATORY_PARAM_EMPTY... | 必填参数未发送、为空或格式错误。 |
| -1103/-1104 | UNKNOWN / UNREAD_PARAM | 发送了未知参数，或未读取所有参数。 |
| -1105/-1106 | PARAM_EMPTY / NOT_REQUIRED | 参数为空，或发送了不需要的参数。 |
| -1108/-1109 | BAD_ASSET / BAD_ACCOUNT | 资产无效或账户无效。 |
| -1110/-1111 | BAD_INSTRUMENT_TYPE / PRECISION | 交易对不正确，或精度超过最大定义值。 |
| -1112/-1113 | NO_DEPTH / WITHDRAW_NOT_NEGATIVE | 交易对无挂单，或提现数量需为负数。 |
| -1114/-1115 | TIF_NOT_REQUIRED / INVALID_TIF | 不需要或无效的 TimeInForce（有效时间）参数。 |
| -1116/-1117 | INVALID_ORDER_TYPE / SIDE | 无效的订单类型或买卖方向。 |
| -1118/-1119 | EMPTY_NEW_CL_ORD_ID... | 新的或原始客户自定义订单 ID 为空。 |
| -1120/-1121 | BAD_INTERVAL / BAD_SYMBOL | 无效的时间间隔或交易对。 |
| -1122/-1125 | INVALID_SYMBOL_STATUS / LISTEN_KEY | 交易对状态不正确，或 listenKey 不存在。 |
| -1126/-1127 | ASSET_NOT_SUPPORTED / MORE_THAN_XX_HOURS | 不支持该资产，或查询时间间隔过大。 |
| -1128/-1130 | OPTIONAL_PARAMS_BAD_COMBO / INVALID_PARAMETER | 可选参数组合无效，或发送的参数数据无效。 |
| -1136 | INVALID_NEW_ORDER_RESP_TYPE | 无效的 newOrderRespType。 |
20xx - 订单处理问题 (Processing Issues)
主要涉及账户状态、余额、仓位以及下单/撤单逻辑冲突。
| 错误代码 | 错误名称 | 错误描述 / 原因 |
|---|---|---|
| -2010 | NEW_ORDER_REJECTED | 新订单被拒绝。 |
| -2011/-2012 | CANCEL_REJECTED / CANCEL_ALL_FAIL | 取消订单被拒绝， 或批量取消失败。 |
| -2013 | NO_SUCH_ORDER | 订单不存在。 |
| -2014/-2015 | BAD_API_KEY_FMT / REJECTED_MBX_KEY | API-key 格式无效，或 IP/权限无效。 |
| -2016/-2017 | NO_TRADING_WINDOW / API_KEYS_LOCKED | 找不到交易窗口，或 API key 被锁定。 |
| -2018/-2019 | BALANCE / MARGIN_NOT_SUFFICIENT | 账户余额不足，或杠杆保证金不足。 |
| -2020/-2021 | UNABLE_TO_FILL / ORDER_WOULD_IMMEDIATELY_TRIGGER | 无法成交，或订单可能被立刻触发。 |
| -2022/-2026 | REDUCE_ONLY_REJECT... | 仅减仓（ReduceOnly）订单被拒绝或当前订单类型不支持。通常因与现有挂单冲突导致。 |
| -2023/-2024 | USER_IN_LIQUIDATION / POSITION_NOT_SUFFICIENT | 用户正处于被强平模式，或持仓不足。 |
| -2025 | MAX_OPEN_ORDER_EXCEEDED | 挂单量达到上限。 |
| -2027/-2028 | MAX_LEVERAGE_RATIO / MIN_LEVERAGE_RATIO | 超出当前杠杆最大持仓/挂单量，或调整杠杆过低导致余额不足。 |
40xx - 过滤器及风控问题 (Filters and other Issues)
最庞大的错误类别，主要涉及价格带保护、数量限制、步进值、多空模式/资产模式切换以及各种风控限制。
| 错误类别 | 常见错误代码及含义摘要 |
|---|---|
| 价格与数量过滤器 | -4001 至 -4014：价格/数量小于0或不满足最小要求、超出最大限制、不符合精度或步进值倍数。 |
| 止盈止损限制 | -4006 至 -4007：触发价不合规；-4183/-4184：订单价格超出触发价与乘数的限制区间。 |
| 账户模式切换 | -4046 至 -4054：保证金模式切换失败（有挂单/持仓时无法切换全仓/逐仓）。-4167 至 -4172：多资产模式与单资产模式切换失败。-4059 至 -4068：单双向持仓模式切换失败（有持仓/挂单时无法切换持仓方向）。 |
| 期权特有错误 | -4063 至 -4081：期权特有的参数、金额、ID、期权费、方向无效或找不到目标。 |
| 杠杆与合规限制 | -4028：杠杆倍数不正确。-4161：逐仓模式下有持仓时无法降低杠杆。-4202 至 -4209：受限于 KYC、注册时间（1个月/X天限制）、国家合规限制或账户开通大户功能，导致无法调整高杠杆（如超20倍）。-4402/-4403：合规要求导致该地区不可用或有杠杆上限限制。 |
| 交易风控 | -4164：订单名义价值过小（通常要求 >= 5 USDT，仅减仓单除外）。-4118：仅减仓订单导致反向持仓及保证金不足。-4192：处于合约冷静期禁止开仓。-4400/-4401：违反量化交易或大资金持仓风控规则，只允许平仓操作。 |
50xx - 订单执行与改单问题 (Order Execution Issues)
主要涉及高级订单类型（FOK/GTX）以及改单（Modify Order）接口的报错。
| 错误代码 | 错误名称 | 错误描述 / 原因 |
|---|---|---|
| -5021 | FOK_ORDER_REJECT | 订单无法立即完全成交，FOK 订单被拒绝且不记录。 |
| -5022 | GTX_ORDER_REJECT | 订单无法仅作为 Maker（做市）成交，Post Only 订单被拒绝且不记录。 |
| -5024 | MOVE_ORDER_NOT_ALLOWED... | 交易对不在交易状态，无法改单。 |
| -5025 | LIMIT_ORDER_ONLY | 目前改单接口仅支持限价单改单。 |
| -5026 | Exceed_Maximum_Modify_Order_Limit | 超过了该单个订单允许的最大改单次数上限。 |
| -5027 | SAME_ORDER | 请求参数与原订单完全相同，无需改单。 |
| -5028 | ME_RECVWINDOW_REJECT | 时间戳在撮合引擎的 recvWindow 之外。 |
| -5029 | MODIFICATION_MIN_NOTIONAL | 改单后订单的名义价值小于规定的最小值（通常为 5U）。 |
| -5037/-5038 | INVALID_PRICE_MATCH | 价格匹配类型错误，或该订单类型不支持价格匹配。 |
| -5039 | INVALID_SELF_TRADE_PREVENTION_MODE | 错误的防自成交（STP）类型。 |
| -5040 | FUTURE_GOOD_TILL_DATE | GTD 订单的有效时间必须大于当前时间+60秒。 |
| -5041 | BBO_ORDER_REJECT | 当前盘口没有深度， 无法匹配 BBO 订单。 |
| -5043 | Existing_Pending_Modification | 该订单已经有一个改单请求正在处理中，请勿并发改单。 |