Skip to the guide
Navigation

BYBIT GLOBAL SPOT · GUIDE 09

Common Bybit API Errors and How to Fix Them

A practical Bybit V5 Spot guide: turn an error code into an access check, a parameter check or an order-state investigation.

TradeMaticPublished, updated & checked · Asia/Sakhalin

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 / scopeWhat it points toNext check
-2015 · SpotExpired Spot API keyKey status
10003UTA: key/environment; WS Order Entry: session countKey / connections
10004 · UTASignature errorSigned request
10005 · UTAMissing API permissionSpot permissions
10010 · UTARequest IP does not match allowed IPsServer's outgoing IP
10002 · UTARequest outside the accepted time windowTime and latency
10001 · UTA; 170121 · SpotInvalid parameters or symbolRequest and pair
170131 · SpotInsufficient balanceUsable funds
170136, 170140 · SpotMinimum quantity or order-value boundaryCurrent Spot minimum
170134, 170137, 170148 · SpotPrice, quantity or amount precisionPrecision and price grid
10006 · UTA; 170005 · SpotRequest or new-order frequency limitReduce the request rate
10000 · UTA; 170007, 170146, 170147 · SpotServer, backend, creation or cancellation timeoutEstablish the operation's outcome
10016 · UTA; 170001 · SpotInternal service errorCheck service and operation state
10014 · UTA; 170141 · SpotDuplicate request or client identifierFind the original operation
170192, 170193, 170194 · SpotOrder/buy price above a cap or sell price below a floorApplicable price bounds
10009, 10024, 10027 · UTARegional availability, compliance or account transaction restrictionAccount 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.

RecordWhy it helps
Time and time zoneMatch the error with the relevant operation.
REST or WebSocketIdentify the applicable code reference.
Endpoint or operationDistinguish reading data, creating an order and cancelling it.
HTTP statusUnderstand the transport response.
retCode and sanitized retMsgRead the application-level result.
Environment and product categoryCheck the key, account and spot scope.
Order identifier, if presentFind 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.

  1. Get the current address from the active TradeMatic interface or connection instructions.
  2. Open the whitelist for the correct Bybit key.
  3. Match the address to the service that actually sends the requests.
  4. 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.

FieldWhat to check
lotSizeFilter.minOrderAmtMinimum order value.
basePrecision, quotePrecisionBase-coin and quote-coin precision.
priceFilter.tickSizeAllowed price increment.
maxLimitOrderQty, maxMarketOrderQtyMaximum 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.

  1. 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.
  2. Price grid: with a hypothetical tick of 0.1, price 10.05 is invalid because 10.05 / 0.1 = 100.5. Prices 10.0 and 10.1 are on the grid, but represent different trading decisions. Do not choose a rounding direction automatically just to pass validation.
  3. Order units: at an assumed price of 2 USDT per base coin, qty=10 with baseCoin means 10 coins worth 20 USDT; with quoteCoin, 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.

  1. Identify the operation. Reading a balance, buying and cancelling need different recovery actions.
  2. Find its saved identifiers. orderId is Bybit's ID; orderLinkId is the client's unique identifier, up to 36 characters. Preserve the original request context.
  3. Check status and fills. Consult the application's order/execution updates, Get Open & Closed Orders, Get Order History and Get Trade History as appropriate.
  4. 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, orderId takes priority.
  5. 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.

Acceptance is a separate stage.

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.
Static decision guide: identify the failure type and the state of any submitted operation first.

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.

Safe example message

“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.