Error Codes
10xx - General Server or Network Issues
Primarily related to network connectivity, request rate limits, authentication, and internal server errors.
| Error Code | Error Name | Description / Reason |
|---|---|---|
| -1000 | UNKNOWN | An unknown error occurred while processing the request. |
| -1001 | DISCONNECTED | Internal error; unable to process the request. Please retry. |
| -1002 | UNAUTHORIZED | Not authorized to execute this request. |
| -1003 | TOO_MANY_REQUESTS | Too many requests / rate limit exceeded (may result in IP ban). Consider using WebSocket. |
| -1004 | DUPLICATE_IP | The IP address is already on the whitelist. |
| -1005 | NO_SUCH_IP | The IP address is not on the whitelist. |
| -1006 | UNEXPECTED_RESP | Unexpected response received from the message bus; execution status unknown. |
| -1007 | TIMEOUT | Timed out waiting for a response from the backend server; execution status unknown. |
| -1008 | Request Throttled | Server overloaded or system-level protection triggered, resulting in rate limiting (only reduce-only / close-position orders are exempt). |
| -1014 | UNKNOWN_ORDER_COMPOSITION | The current combination of order parameters is not supported. |
| -1015 | TOO_MANY_ORDERS | The number of new orders exceeds the limit. |
| -1016 | SERVICE_SHUTTING_DOWN | This service is unavailable. |
| -1020 | UNSUPPORTED_OPERATION | This operation is not supported. |
| -1021 | INVALID_TIMESTAMP | Invalid timestamp (outside recvWindow, or more than 1000ms ahead of server time). |
| -1022 | INVALID_SIGNATURE | Invalid request signature. |
| -1023 | START_TIME_GREATER_THAN_END_TIME | The start time parameter is after the end time. |
| -1099 | NOT_FOUND | Not found, not authenticated, or not authorized. |
11xx - Request Parameter Issues
Primarily related to format, type, missing, or range errors in API request parameters.
| Error Code | Error Name | Description / Reason |
|---|---|---|
| -1100 | ILLEGAL_CHARS | Illegal characters found in a parameter. |
| -1101 | TOO_MANY_PARAMETERS | Too many parameters or duplicate parameter values detected. |
| -1102 | MANDATORY_PARAM_EMPTY... | A mandatory parameter was not sent, is empty, or is malformed. |
| -1103/-1104 | UNKNOWN / UNREAD_PARAM | An unknown parameter was sent, or not all parameters were read. |
| -1105/-1106 | PARAM_EMPTY / NOT_REQUIRED | A parameter is empty, or an unnecessary parameter was sent. |
| -1108/-1109 | BAD_ASSET / BAD_ACCOUNT | Invalid asset or invalid account. |
| -1110/-1111 | BAD_INSTRUMENT_TYPE / PRECISION | Incorrect trading pair, or precision exceeds the maximum defined value. |
| -1112/-1113 | NO_DEPTH / WITHDRAW_NOT_NEGATIVE | No open orders for the trading pair, or withdrawal amount must be negative. |
| -1114/-1115 | TIF_NOT_REQUIRED / INVALID_TIF | TimeInForce parameter is not required or is invalid. |
| -1116/-1117 | INVALID_ORDER_TYPE / SIDE | Invalid order type or order side. |
| -1118/-1119 | EMPTY_NEW_CL_ORD_ID... | New or original client custom order ID is empty. |
| -1120/-1121 | BAD_INTERVAL / BAD_SYMBOL | Invalid time interval or trading pair. |
| -1122/-1125 | INVALID_SYMBOL_STATUS / LISTEN_KEY | Incorrect trading pair status, or listenKey does not exist. |
| -1126/-1127 | ASSET_NOT_SUPPORTED / MORE_THAN_XX_HOURS | Asset not supported, or query time range is too large. |
| -1128/-1130 | OPTIONAL_PARAMS_BAD_COMBO / INVALID_PARAMETER | Invalid combination of optional parameters, or invalid parameter data sent. |
| -1136 | INVALID_NEW_ORDER_RESP_TYPE | Invalid newOrderRespType. |
20xx - Order Processing Issues
Primarily related to account status, balance, positions, and order/cancel logic conflicts.
| Error Code | Error Name | Description / Reason |
|---|---|---|
| -2010 | NEW_ORDER_REJECTED | New order rejected. |
| -2011/-2012 | CANCEL_REJECTED / CANCEL_ALL_FAIL | Cancel order rejected, or batch cancel failed. |
| -2013 | NO_SUCH_ORDER | Order does not exist. |
| -2014/-2015 | BAD_API_KEY_FMT / REJECTED_MBX_KEY | Invalid API key format, or invalid IP/permissions. |
| -2016/-2017 | NO_TRADING_WINDOW / API_KEYS_LOCKED | Trading window not found, or API key is locked. |
| -2018/-2019 | BALANCE / MARGIN_NOT_SUFFICIENT | Insufficient account balance, or insufficient margin. |
| -2020/-2021 | UNABLE_TO_FILL / ORDER_WOULD_IMMEDIATELY_TRIGGER | Unable to fill, or order would be immediately triggered. |
| -2022/-2026 | REDUCE_ONLY_REJECT... | Reduce-only order rejected, or current order type not supported. Usually caused by conflicts with existing open orders. |
| -2023/-2024 | USER_IN_LIQUIDATION / POSITION_NOT_SUFFICIENT | User is in liquidation mode, or position is insufficient. |
| -2025 | MAX_OPEN_ORDER_EXCEEDED | Maximum number of open orders reached. |
| -2027/-2028 | MAX_LEVERAGE_RATIO / MIN_LEVERAGE_RATIO | Exceeds maximum position/open order size for current leverage, or reducing leverage would cause insufficient balance. |
40xx - Filter and Risk Control Issues
The largest error category, primarily related to price band protection, quantity limits, tick size, position mode / asset mode switching, and various risk control restrictions.
| Error Category | Common Error Codes and Summary |
|---|---|
| Price and Quantity Filters | -4001 to -4014: Price/quantity is less than 0, does not meet the minimum requirement, exceeds the maximum limit, or does not conform to precision or tick size multiples. |
| Take Profit / Stop Loss Limits | -4006 to -4007: Trigger price is invalid; -4183/-4184: Order price exceeds the limit range defined by trigger price and multiplier. |
| Account Mode Switching | -4046 to -4054: Margin mode switch failed (cannot switch between cross/isolated margin when there are open orders/positions). -4167 to -4172: Multi-asset mode and single-asset mode switch failed. -4059 to -4068: One-way/hedge position mode switch failed (cannot switch position direction when there are positions/open orders). |
| Options-Specific Errors | -4063 to -4081: Options-specific parameter, amount, ID, premium, or direction is invalid or target not found. |
| Leverage and Compliance Limits | -4028: Incorrect leverage multiplier. -4161: Cannot reduce leverage when holding positions in isolated margin mode. -4202 to -4209: Restricted by KYC, registration time (1 month / X days limit), country compliance restrictions, or account VIP feature activation, preventing high leverage adjustments (e.g., above 20x). -4402/-4403: Region unavailable or leverage cap imposed due to compliance requirements. |
| Trading Risk Control | -4164: Order notional value too small (typically must be >= 5 USDT, except for reduce-only orders). -4118: Reduce-only order would cause a reverse position and insufficient margin. -4192: Opening positions is prohibited during the contract cooling-off period. -4400/-4401: Violation of quantitative trading or large position risk control rules; only close-position operations are allowed. |
50xx - Order Execution and Modification Issues
Primarily related to advanced order types (FOK/GTX) and the Modify Order endpoint errors.
| Error Code | Error Name | Description / Reason |
|---|---|---|
| -5021 | FOK_ORDER_REJECT | Order cannot be immediately fully filled; FOK order rejected and not recorded. |
| -5022 | GTX_ORDER_REJECT | Order cannot be filled solely as a maker; Post Only order rejected and not recorded. |
| -5024 | MOVE_ORDER_NOT_ALLOWED... | Trading pair is not in trading status; order modification not allowed. |
| -5025 | LIMIT_ORDER_ONLY | The modify order endpoint currently only supports limit order modifications. |
| -5026 | Exceed_Maximum_Modify_Order_Limit | Exceeded the maximum number of modifications allowed for a single order. |
| -5027 | SAME_ORDER | Request parameters are identical to the original order; no modification needed. |
| -5028 | ME_RECVWINDOW_REJECT | Timestamp is outside the matching engine's recvWindow. |
| -5029 | MODIFICATION_MIN_NOTIONAL | The notional value of the modified order is below the minimum required value (typically 5 USDT). |
| -5037/-5038 | INVALID_PRICE_MATCH | Price match type is incorrect, or this order type does not support price matching. |
| -5039 | INVALID_SELF_TRADE_PREVENTION_MODE | Invalid self-trade prevention (STP) mode. |
| -5040 | FUTURE_GOOD_TILL_DATE | The valid time for a GTD order must be greater than the current time + 60 seconds. |
| -5041 | BBO_ORDER_REJECT | No depth available in the current order book; BBO order cannot be matched. |
| -5043 | Existing_Pending_Modification | A modification request for this order is already being processed; do not submit concurrent modifications. |