Common Error Handling
This page explains common errors, why they occur, and how to resolve them. For the full list of error codes, see REST API Error Code or WebSocket Error Code.
WebSocket Errors
30002 — Unrecognized request
The request message format is invalid. Check that the subscription or request payload is valid JSON and matches the expected schema.
30004 — User not logged in / User must be logged in
A subscription message was sent before the login response was received. Always wait for a successful login response before sending subscription messages.
Authentication Errors
40006 — Invalid ACCESS_KEY
Check that the ACCESS-KEY in your request header is correct.
40008 — Request timestamp expired
The timestamp in your request deviates too far from the server time. Sync your local clock using Get Server Time.
40009 — sign signature error
Common causes and fixes:
- Signature algorithm error → follow the Signature Guide
- Query string or body was URL-encoded before signing (breaks when coin names contain non-ASCII characters) → do not URL-encode the query string or body before signing
Rate Limit Errors
429 — Too Many Requests
The API rate limit has been exceeded. Reduce your request frequency and comply with the rate limits for each endpoint.
40725 — service return an error
Usually caused by a server deployment. Retry after receiving the error response.
Order Errors
25003 — Concurrent operation, please retry
In one-way position mode, if the total quantity of all reduce-only orders exceeds the current position size, the system will cancel existing orders before placing new ones. In cancel-then-place scenarios, the new order can arrive before the cancellation is processed by the matching engine. No special action is needed — retry after a short delay.
25102 — Trading pair temporarily closed for maintenance
The trading pair may not yet support UTA orders, may not be launched on v3, or may be under maintenance.
25101= short-term maintenance or not open yet;25102= longer maintenance or near-delisting;40309= already delisted.
25105 — This contract does not support opening positions
The trading pair does not support opening positions, or it has been delisted. Check whether the unified contract is live or refer to delisting announcements.
25110 — This coin is not supported for deposits into the unified account
This coin cannot be transferred into the unified account. No workaround is available.
25212 — Duplicate clientOid
Idempotency is checked against the current order status: clientOid cannot be reused while an order is open; it can be reused after the order is filled or cancelled.
25229 — Total positions exceed the current limit of {0} positions
The maximum position count of 200 has been reached. Keep position count below 200, or distribute positions across sub-accounts.
25232 — Reduce-only orders will only reduce your position
This occurs when non-reduce-only orders exist and the combined quantity of both order types exceeds the position size, while the non-reduce-only order price is more favorable. Cancel or modify existing non-reduce-only orders before placing a reduce-only order.
25234 — Remaining quantity for regular orders is 0
An IO position limit was triggered. Adjust your order size and retry. Learn more
25567 — Exceeded the maximum quantity of contract orders
The order size exceeds the single-order quantity limit. Check maxMarketOrderQty (max market order size) and maxOrderQty (max limit order size) from the Get Instruments endpoint.
25568 — The order does not meet the modification requirements
Preset TP/SL orders and market orders cannot be modified. Do not attempt to modify these order types.
25574 — Reduce-only order protection
When non-reduce-only orders exist, the modified price cannot be more favorable than the existing reduce-only order price. Adjust the modified price so it does not take priority over the reduce-only order.
45110 — Less than the minimum order amount
Order value is below the minimum (5 USDT for futures, 1 USDT for spot). Note that in unified accounts, the backend resets the effective order quantity to match the trading pair's precision — this can silently reduce the order value below the minimum (e.g., SYRUPUSDT with a step of 10: placing 16 × 0.4484 → effective qty 10 × 0.4484 = 4.484 USDT, rejected). Ensure the final effective order value clears the minimum threshold.
45116 — The count of positions held by the account exceeds the maximum count
The maximum position count (200) has been exceeded. Keep positions below 200, or distribute across sub-accounts.
45119 — This symbol does not support position opening operation
The trading pair's status has been restricted or the pair has been delisted. Use Get Instruments to check the trading pair status, or refer to delisting announcements.
45121 — The reasonable mark price deviates too much from the market
The reasonable mark price has deviated too far from the market price, making the current leveraged position high-risk. See the Bitget support article for details.
45001 — Unknown error
Usually caused by a server deployment. Retry after receiving the error response.
40908 — Concurrent operation failed
Occurs when position processing takes longer than usual (accounts with many positions), or when a close order arrives before a prior cancellation is fully processed. Wait for the previous operation to complete before sending a new request.
40710 — Abnormal account status
Account status is abnormal. Contact customer support.
40760 — Unable to place order due to ongoing liquidation
The account is currently being liquidated — trading and transfers are blocked until the process completes. Wait for the liquidation to finish before retrying.
40022 — The business of this account has been restricted
Two common causes:
- Sub-account trading permission is not enabled → enable trading permission for the sub-account
- Account under risk control → contact customer support to verify the account's risk control status
40715 — Exceeded the maximum open count
The maximum openable quantity has been reached. Use Get Max Open Available to check the current limit.
40034 — Parameter does not exist
One or more request parameters are incorrect. Verify all parameters against the API documentation.
40763 — Exceeds position tier limit
The position size exceeds the current position tier limit. See Position Tier for the applicable limits.
40774 — The order type for unilateral position must also be the unilateral position type
Order parameters do not match the current position mode (tradeSide / posSide mismatch). Use the correct combination for your account's position mode:
| Mode | Action | Parameters |
|---|---|---|
| Hedge | Open long | side=buy&posSide=long |
| Hedge | Open short | side=sell&posSide=short |
| Hedge | Close long | side=sell&posSide=long |
| Hedge | Close short | side=buy&posSide=short |
| One-way | Open long | side=buy |
| One-way | Open short | side=sell |
| One-way | Close long | side=sell&reduceOnly=yes |
| One-way | Close short | side=buy&reduceOnly=yes |
40815 — The order price is higher than the highest bid price
The buy order price exceeds the current highest bid. Adjust the price downward.
40816 — The order price is lower than the lowest selling price
The sell order price is below the current lowest ask. Adjust the price upward.
40922 — Only work order modifications are allowed
The order cannot be modified because it is fully filled, cancelled, or rejected. Only unfilled or partially-filled orders can be modified.
41117 — Selling price cannot be lower than the limit
The order price is outside the allowed buy/sell spread range (buyLimitPriceRatio / sellLimitPriceRatio). Check these values from Get Instruments and place orders within the allowed range.
43027 — The minimum order value is not met
When placing a buy order, the system uses the lower of the mark price and the order price. If the mark price is below the order price, an order priced at exactly 5 USDT may still be rejected. Avoid placing orders at the exact boundary — leave a small margin above the minimum.
45118 — Reached the upper limit of orders
The pending order count has reached the platform limit. Limits by account type:
- Futures: 200 unfilled orders per symbol, 400 per business line (UID-level)
- Max position count: 200 per business line (UID-level)
- Spot margin: 100 open orders per trading pair per UID, 1,000 total
- Spot: 200 open orders per trading pair per UID, 1,000 total
Reduce the number of pending orders to proceed.
22046 — The order price exceeds the minimum price limit
The order price is below the minimum allowed. Adjust the price upward to meet the minimum limit.
22047 — The order price exceeds the maximum price limit
The order price exceeds the maximum allowed. Adjust the price downward to stay within the limit.
22048 — Exceeded personal limit, unable to delegate
The user's borrowable quantity has reached the personal limit. Check the current limit from Get Max Open Available.
22067 — ADL processing, forbid operate the symbol
The symbol is temporarily blocked due to ADL (Auto-Deleveraging) processing. Wait for the ADL process to complete before retrying.
12001 — {0} can be used at most
Insufficient account balance. Top up the account and retry.
13008 — Traders minimum place orderSize is {0}
The order size is below the trader's minimum requirement. Increase the order size to meet the minimum.