An apparent Bybit API failure can come from access settings, order parameters, connectivity or the exchange service. “The bot does not buy” and “no response” do not identify the cause. Start with the operation, time and sanitized response: the same code can mean different things in different API scopes.
This guide covers Bybit V5 and ordinary Spot trading without borrowing, with a separate checklist for TradeMatic's Bybit Global connection. Check category=spot; futures and margin rules do not automatically apply. Official documentation was checked on 19 November 2026; check current pair constraints before the operation.
Contents
Quick error lookup
The table follows the UTA and Spot Trade sections of Bybit's Error Codes. Check the API section as well as the number. In particular, 10003 has a different meaning in WS Order Entry.
| Code / scope | What it points to | Next check |
|---|---|---|
-2015 · Spot | Expired Spot API key | Key status |
10003 | UTA: key/environment; WS Order Entry: session count | Key / connections |
10004 · UTA | Signature error | Signed request |
10005 · UTA | Missing API permission | Spot permissions |
10010 · UTA | Request IP does not match allowed IPs | Server's outgoing IP |
10002 · UTA | Request outside the accepted time window | Time and latency |
10001 · UTA; 170121 · Spot | Invalid parameters or symbol | Request and pair |
170131 · Spot | Insufficient balance | Usable funds |
170136, 170140 · Spot | Minimum quantity or order-value boundary | Current Spot minimum |
170134, 170137, 170148 · Spot | Price, quantity or amount precision | Precision and price grid |
10006 · UTA; 170005 · Spot | Request or new-order frequency limit | Reduce the request rate |
10000 · UTA; 170007, 170146, 170147 · Spot | Server, backend, creation or cancellation timeout | Establish the operation's outcome |
10016 · UTA; 170001 · Spot | Internal service error | Check service and operation state |
10014 · UTA; 170141 · Spot | Duplicate request or client identifier | Find the original operation |
170192, 170193, 170194 · Spot | Order/buy price above a cap or sell price below a floor | Applicable price bounds |
10009, 10024, 10027 · UTA | Regional availability, compliance or account transaction restriction | Account status and official support |
10018 is crossed out in the current reference and is not an active main code in this guide. For 10016, WS Order Entry also lists service restart; retain the connection context. A listed minimum-quantity error does not make the deprecated Spot minOrderQty field the current validation rule.
How to read a Bybit API error
Record a short, sanitized description before changing settings. Keep account-specific identifiers in a private support channel.
| Record | Why it helps |
|---|---|
| Time and time zone | Match the error with the relevant operation. |
| REST or WebSocket | Identify the applicable code reference. |
| Endpoint or operation | Distinguish reading data, creating an order and cancelling it. |
| HTTP status | Understand the transport response. |
retCode and sanitized retMsg | Read the application-level result. |
| Environment and product category | Check the key, account and spot scope. |
| Order identifier, if present | Find the actual operation and its state. |
Educational response, with no account data:
{
"retCode": 170131,
"retMsg": "Balance insufficient",
"result": {},
"retExtInfo": {},
"time": 1795046400000
}
Here, retCode identifies the balance problem, retMsg describes it, result holds business data, retExtInfo holds additional information and time is a UTC timestamp in milliseconds. The HTTP status is recorded separately: HTTP 200 does not itself establish API success. See Integration Guidance.
Scope changes meaning: UTA/REST 10003 points to the key and environment; WS Order Entry 10003 concerns the number of sessions for a UID. An HTTP 403 can have several causes, so it does not establish an IP-whitelist problem. If no response arrived, that alone does not establish that no order was created.
1. Invalid, deleted or expired API key
What it looks like: UTA/REST 10003, Spot -2015, or a connection check that cannot authenticate. Common causes include the wrong account or subaccount, an inactive key, extra spaces, or an environment mismatch.
Check and correct: select the intended key in Bybit API Management and confirm that it is active and belongs to the correct main account or subaccount. Check its purpose and supported key type. When entering it again, use its original secret; a secret from another key will not work even if the labels match.
Mainnet, testnet and demo are separate contexts. Global mainnet uses api.bybit.com, testnet uses api-testnet.bybit.com, and mainnet demo has its own account/key context and api-demo.bybit.com. Changing the hostname does not change a key's environment or make a regional platform compatible. Read Integration Guidance and Demo Trading Service.
Check the expiry conditions for that key. Bybit's API Key Information documents deadlineDay and expiredAt with conditions for keys without bound IPs or after a password change; there is no single lifespan that applies to every key. When a replacement is necessary, use the Bybit API key guide and the application's supported key type.
Verify: use a supported read-only connection check. Successful authentication confirms this stage; permission to trade still needs a separate check. TradeMatic's verified connection requirements are below.
2. Insufficient API permissions
What it looks like: balances can be read, but 10005 appears when a trade is attempted. Read-only access and Spot trading permission are different capabilities.
Check and correct: a developer can inspect readOnly and permissions.Spot; Bybit documents readOnly=0 for read/write and SpotTrade as the Spot permission. The key-information query itself does not prove that the key can place an order. Check the application's actual requirements before editing the intended key.
Withdrawals, transfers and derivatives permissions are separate in Get API Key Information. Adding them does not fix ordinary Spot trading access. Verify: repeat the application's connection and permission check after saving the correct settings; do not place an extra order merely to test a key.
3. The IP whitelist does not match the request source
What it looks like: 10010 means the request's source IP does not match the key's allowed IPs. With a server bot, the relevant address is the outgoing IP of the server making the API request.
- Get the current address from the active TradeMatic interface or connection instructions.
- Open the whitelist for the correct Bybit key.
- Match the address to the service that actually sends the requests.
- Save the correction and repeat a safe connection check.
Your phone's, home router's or website's IP does not automatically describe a remote bot's request; NAT and proxies can also affect the outgoing address. Ask the server administrator to verify it when using your own application. Do not disable the restriction or allow every address as the standard fix. No fixed server IP is published here. The code's scope is in Error Codes.
4. Signature errors and the request time window
10004 concerns signing; 10002 concerns request timing. They need different checks. Re-entering unrelated trading parameters will not repair an incorrectly signed request.
For a developer: match HMAC or RSA signing to the key type, then check the exact query parameters or JSON body, encoding, request headers and millisecond timestamps. Compare the sending server's clock with Bybit time and inspect network delay. The documented condition is:
server_time - recv_window <= timestamp < server_time + 1000
Use clock synchronization and investigate latency. An arbitrary increase in recv_window is not a universal fix. The current signing headers and timing rule are documented in Integration Guidance.
For a TradeMatic user: retain the time, action and sanitized code/message, then contact support if the supported connection settings are correct. Changing your phone's clock will not synchronize a request sent by the bot server. Verify: the administrator checks server time and a safe authenticated read, while the user checks the connection result.
5. Insufficient funds for the particular operation
What it looks like: Spot 170131 even though the account displays assets. The total USD valuation, a particular coin's balance, funds in the trading account, assets tied to existing orders and the amount usable for a new operation are different measures.
Check: confirm the trading account, pair, side, units and fees. A buy usually needs quote currency; a sell needs the base asset. Inspect open orders that already commit those assets. A Funding balance is not automatically a usable Unified trading balance.
For a developer: Bybit's wallet documentation deprecates availableToWithdraw for UNIFIED from 9 January 2025 and also deprecates free. locked describes Spot open-order commitments; the current spotBorrow logic changes the interpretation of walletBalance. Do not turn an old sample or walletBalance − locked into a universal availability formula.
Correct and verify: establish which asset or reservation prevents the intended operation, then decide whether to change that operation. Do not automatically cancel every order, enable borrowing or assume a deposit is the only fix. Check the revised available funds and applicable fees before a planned trade.
6. Spot parameters, minimums, precision and price
What it looks like: 10001 or 170121 for the request or symbol; 170136/170140 near a minimum; 170134/170137/170148 for price, quantity or amount precision. First confirm category=spot, the correct uppercase pair without an accidental separator, its trading status, the side, order type and required parameters.
Check the current Spot specification: use the Spot section of Get Instruments Info for the chosen symbol.
| Field | What to check |
|---|---|
lotSizeFilter.minOrderAmt | Minimum order value. |
basePrecision, quotePrecision | Base-coin and quote-coin precision. |
priceFilter.tickSize | Allowed price increment. |
maxLimitOrderQty, maxMarketOrderQty | Maximum quantity for the chosen Limit or Market type. |
minOrderQty is deprecated in the Spot schema in favor of minOrderAmt; maxOrderQty and maxOrderAmt point to the current quantity caps. The document's example JSON still includes old fields. Follow the current definitions and values for the pair. Futures fields qtyStep and minNotionalValue are not a universal Spot schema.
Codes 170192, 170193 and 170194 concern applicable price caps or floors. A valid decimal format and tick multiple can still fail a price bound. Check the returned message and current restrictions; do not move the intended price automatically.
Three educational examples
These values are invented for arithmetic, not current limits for any Bybit pair.
- Minimum value: with a hypothetical minimum of 10 USDT, a price of 2 USDT and quantity of 4 base coins, the order value is
2 × 4 = 8 USDT. It is below that minimum. - Price grid: with a hypothetical tick of
0.1, price10.05is invalid because10.05 / 0.1 = 100.5. Prices10.0and10.1are on the grid, but represent different trading decisions. Do not choose a rounding direction automatically just to pass validation. - Order units: at an assumed price of 2 USDT per base coin,
qty=10withbaseCoinmeans 10 coins worth 20 USDT; withquoteCoin, it means 10 USDT, equivalent to 5 coins. Fees and price movement are omitted from this arithmetic example.
Place Order lets marketUnit specify base quantity or quote value for Spot Market orders; Market Buy uses quote value by default. Check the actual unit rather than relying on the same number to mean the same trade, especially when moving code between sides and order types.
Correct and verify: use decimal arithmetic, validate the intended units and round only within the strategy's rules. Recheck value, quantity, limits, funds and fees after rounding. The user must choose any budget or desired-price change. For planned limit exits, see automatic selling at a target price.
7. Too many requests or new orders
What it looks like: 10006 for request frequency or 170005 for new-order frequency. Distinguish shared IP limits, UID/endpoint quotas, order-creation limits and WebSocket connection limits. One service's repeated requests can consume a shared allowance.
For a developer: inspect the response headers:
X-Bapi-Limit— the applicable endpoint quota.X-Bapi-Limit-Status— the remaining allowance.X-Bapi-Limit-Reset-Timestamp— reset time when the limit is exceeded; otherwise a current timestamp, so it is not always a future retry deadline.
Correct: stop the burst, coordinate request pacing and follow the applicable cooldown. For a confirmed HTTP 403 with access too frequent, Bybit instructs clients to end all corresponding HTTP sessions and wait at least 10 minutes. This instruction applies to that condition, not every 403. See Rate Limit Rules.
For a TradeMatic user: avoid repeated command taps while a request is pending; provide the time and sanitized error to support if the issue persists. Verify: after the required cooldown and corrected pacing, use an appropriate read-only check. For an earlier create/cancel request, also establish its outcome before another trade.
8. Timeouts, internal failures and duplicate requests
10000, 170007, 170146 and 170147 concern timeouts; 10016 and 170001 concern internal errors in the cited REST scopes. A failed read can often be checked again with appropriate pacing. A timeout during order creation does not prove that the order was never created.
- Identify the operation. Reading a balance, buying and cancelling need different recovery actions.
- Find its saved identifiers.
orderIdis Bybit's ID;orderLinkIdis the client's unique identifier, up to 36 characters. Preserve the original request context. - Check status and fills. Consult the application's order/execution updates, Get Open & Closed Orders, Get Order History and Get Trade History as appropriate.
- Check search scope and delay. Use the correct account, category, identifiers, filters and time window, and retrieve additional result pages where needed. If both identifiers are supplied,
orderIdtakes priority. - Decide only after reconciliation. An unfilled open order, a partial fill, a complete fill and a confirmed rejection imply different next actions. If uncertainty remains, involve support instead of sending another purchase.
The open-order query defaults to open records. A completed order may already be absent; its recent closed cache holds at most 500 records and can be cleared by a Bybit service update or restart. History can lag. It defaults to seven days with a maximum seven-day range per request; fully cancelled, rejected and deactivated records have a 24-hour query limit, and records beyond seven days are limited to orders with fills. Executions can include several fills for one order. An empty or incomplete search is not proof that creation failed.
Bybit states that creation acknowledgment confirms request acceptance; processing is asynchronous. Confirm the order state and executions. The same distinction applies to cancellation acknowledgment: a cancellation timeout does not confirm cancellation, and a fill may have occurred.
10014 or 170141 is a reason to find the original request or client identifier. Identification and duplicate detection do not provide a blanket guarantee that every retry is idempotent. Do not change the client identifier merely to bypass a duplicate message: that may produce an additional order.
Verify recovery: reconcile the intended operation with the exchange's actual state and fills before allowing a new financial action. There is no unconditional create-order retry loop in this guide.
9. Connectivity, DNS, TLS and WebSocket
What it looks like: a hostname cannot be resolved, a connection cannot be established, TLS validation fails, a stream disconnects or expected messages stop arriving. Private-stream authentication can also fail while public prices remain available.
Check and correct: the application developer or administrator checks DNS, network access, certificates, server time, proxy behavior, endpoint/environment, heartbeat and subscription acknowledgments. An open connection alone does not confirm the correct subscription.
Bybit's WebSocket Connect separates the public Spot stream wss://stream.bybit.com/v5/public/spot and private account stream wss://stream.bybit.com/v5/private. Public topics need no authentication; private topics do. A working price feed does not authenticate a key. Testnet has its own host, which must match the key's environment.
Use controlled reconnection and resubscribe as required; repeatedly opening connections can itself hit limits. A quiet private stream can also mean no relevant account changes occurred, so check the subscription and state. For 10003 in WS Order Entry, check the session count. Keep TLS certificate validation enabled. A TradeMatic user can retain the time, command and sanitized message; reconnecting Telegram on a phone does not itself restore the trading server's exchange connection.
Verify: confirm subscriptions and expected updates, then reconcile balances, orders and executions. Losing a connection does not itself cancel exchange orders, so do not treat a quiet screen as an empty account or a confirmed cancellation.
10. Account restrictions and service availability
In the current UTA reference, 10009 concerns regional service availability, 10024 compliance rules and 10027 restricted transactions. Read the actual message, check account notifications and contact official Bybit support when required. Error Codes defines their scope.
Recreating a key, changing domains or repeating an order does not establish that such a restriction is resolved. Follow the account's official review process and verify the resulting account status before an intended operation.
If the error appears in TradeMatic
TradeMatic supports ordinary Spot trading on Bybit Global MAINNET with system-generated HMAC keys. Trading requires a supported UTA 2.0 account, Read/Write and SpotTrade, with read-only mode disabled. Demo, Testnet and RSA PEM are not supported by the current connection. Withdraw, Transfer and derivatives permissions are unnecessary.
In your private bot chat, open /settings to review the connection, key permissions, trading state, purchase amount, thresholds, delay, and separate market-data and account-data statuses. Access to settings requires accepted terms and valid access to the bot. To obtain the current whitelist IP, select a pair during first setup; for an existing connection, press “Update Bybit keys” and select a pair. The key-entry prompt shows the address. If you only needed the address, /cancel ends temporary setup while preserving the active connection and trading state. If the address is unconfirmed, ask support; do not use the website address.
/balance shows confirmed available and locked balances for the selected account; /orders shows open Spot orders for the selected pair; /ordersw shows the bot’s tracked current orders; /help lists commands. These lists do not replace order and execution history. For a ready account, /start starts trading automation, so it is not a universal connection test.
No new purchase may mean incomplete setup, unavailable settings access, STOP, insufficient available funds, waiting for a strategy threshold or delay, reconciliation of a current operation, or a Bybit restriction. Fresh-data-unconfirmed and waiting messages are TradeMatic states, not Bybit retCode values. /stop stops new purchases; existing bot-owned lots and standing sell orders remain supervised.
The bot synchronizes time, applies cooldowns for rate limits, and reconnects WebSocket with a limited number of attempts. This does not fix an invalid key, permissions, IP or account restrictions. When a submitted order’s outcome is unknown, the bot reconciles saved identifiers and executions. Do not initiate another purchase to bypass a timeout or duplicate response; if uncertainty persists, send support the time, action and a redacted message.
Choose the next action
What happened to the request?
- Access rejected → check the key, environment, permissions, IP, signature and time → use the supported connection check.
- Parameters or funds rejected → check the pair, units, available coin and current Spot rules → validate the final size.
- Frequency limit confirmed → stop extra requests, observe the required pause → read at a moderate pace and reconcile.
- No final create/cancel result → find the original identifiers, order and executions → decide on a repeat after establishing the outcome.
What to send to support
Provide the time and time zone, intended action, pair, code and sanitized message; say whether you used TradeMatic or your own application and whether the issue repeats. For a specific order, send its identifiers through the appropriate private support channel.
“19 November 2026, 12:40 UTC. A TradeMatic balance check returned 10010. Pair: BTCUSDT. It repeats. I did not use a trading command to test it. Please confirm the current IP for the whitelist.” This is an educational example with no account identifiers.
For TradeMatic, contact official support; for Bybit account restrictions, contact the exchange. Exclude API Secret, the full API key, request signatures, passwords, cookies and raw logs. This article has no key-check form and does not ask you to enter credentials on the site.
Frequently asked questions
Why does a key work in one application but fail in another?
Compare the account, environment, supported key type, permissions and the server's outgoing IP. A successful request in one application does not prove that another uses the same settings or performs the same operation.
Why can I see my balance but cannot create an order?
Reading data does not prove read/write access or SpotTrade permission. Also check the application's operating mode, usable funds and order parameters. The absence of a new trade does not itself establish an API error. Do not add withdrawal or transfer rights to solve a Spot-order problem.
Which IP should I add for a remote bot?
The outgoing IP of the server sending the API request. Get TradeMatic's current address from its active connection interface or instructions; your phone's IP is not the remote server's address.
Why does a request-time error occur?
The sending server's time, millisecond timestamp or network delay can place a request outside Bybit's window. A server bot needs its server clock checked; changing the user's phone clock does not synchronize that server.
Why can an order fail despite sufficient total account value?
The total can include other coins or assets committed elsewhere. Check the needed coin, trading account, open-order commitments, units and fees. An overall USD valuation is not the amount available for a particular Spot order.
Why do the amount or price fail validation?
Check the selected pair's current Spot minimum, base/quote precision, price tick, order-type maximum and price bounds. A valid number of decimal places alone does not prove that a price is on the tick grid. Recheck the full order after rounding.
Can I repeat a purchase after a timeout?
First find the original operation using saved identifiers and reconcile its status and executions, allowing for search scope and data delays. A timeout does not prove failure; changing the identifier to bypass a duplicate can create another purchase.
Are exchange orders cancelled when the connection drops?
A dropped connection does not confirm cancellation. After reconnecting, restore subscriptions and reconcile the actual order and execution state, including partial fills. Even an acknowledgment accepting cancellation still requires confirmation of its outcome.
What information should I send to support?
Time and time zone, action, pair, sanitized code/message, the application used and whether it repeats. Share order identifiers privately where relevant. Never include API Secret, full keys, signatures, passwords, cookies or raw logs.
Official sources and scope
Official documentation and current product behavior checked 19 November 2026. Definitions below apply within their documented API/product scope. All three arithmetic examples are hypothetical. Review risks and TradeMatic's operating rules before using automation.
Connection and next steps
Use the TradeMatic connection checklist and Telegram control guide for setup. Before allowing new entries, review the algorithm's operating rules, trading risks and service terms.