OKX API Errors and Troubleshooting Checklist: Fix It With This Table

When you write quant scripts, you may get stuck not on the strategy but on a single line of red error text: the script starts up, the terminal spits out a string of incomprehensible codes and English, and you freeze. The good news is that OKX API errors come in just a handful of high-frequency flavors, and once you know what each looks like and what cause it maps to, troubleshooting gets a lot faster.

This piece collects the common OKX API errors into one checklist. The heart of it is a single error-code reference table: when something breaks, find your error by code or keyword in the table, then read the matching item-by-item fix below. By the end you should be able to resolve most errors yourself in minutes, instead of staring blankly at red text.

Learn to read the error first: code + msg

Step one in debugging is reading the error itself. When an OKX endpoint errors out, it returns three pieces of information:

• HTTP status code: the coarsest layer, like 401 (auth problem), 429 (too many requests), 400 (the request itself is wrong).
• code: OKX's own numeric error code, pointing most precisely at the type of problem. This is your main basis for troubleshooting.
• msg: a text description that helps confirm the direction, sometimes pointing out exactly which field is wrong.

If you use ccxt, it wraps these raw errors into more readable exception types—an auth problem throws AuthenticationError, a rate limit throws RateLimitExceeded, insufficient balance throws InsufficientFunds. The exception message generally carries OKX's original code and msg too. A good habit is to print them clearly with try/except:

import ccxt

okx = ccxt.okx({
    'apiKey':   'YOUR_apiKey',
    'secret':   'YOUR_secret',
    'password': 'YOUR_Passphrase',
    'enableRateLimit': True,
})

try:
    balance = okx.fetch_balance()
    print('USDT free:', balance['USDT']['free'])
except ccxt.InvalidNonce as e:
    print('Timestamp expired (50102), resync the clock and retry:', e)
except ccxt.AuthenticationError as e:
    print('Auth failed, read the code in the error before deciding what to check:', e)
except ccxt.RateLimitExceeded as e:
    print('Rate limited, slow down requests:', e)
except ccxt.BaseError as e:
    print('Other error, look at the raw code/msg:', e)

Note down that code and msg from the exception as-is, cross-check the table below, and you can basically pin down which class of problem it is.

High-frequency error reference table

The table below covers the errors beginners easily hit. The error-code meanings in the table were checked in 2026-10 against the Error Code section of OKX's API v5 docs (OKX occasionally adjusts code values, so if one doesn't match, defer to the msg text and the official docs); the point is to line up "cause → fix." The auth class especially has to be worked by code: both look like "can't connect," but 50113 and 50105 send you looking at completely different things.

How to fix each one

The table gives direction; this section gives detail. Read down from whichever one you hit.

Auth class (50101 / 50102 / 50105 / 50110 / 50111 / 50112 / 50113) and permission class (50120)

At the HTTP layer every auth failure is a 401, and in ccxt most of them raise AuthenticationError (the PermissionDenied that 50110 raises is a subclass of it). The exception is 50102, timestamp expired: in ccxt's master-branch source as of 2026-09 it maps to InvalidNonce, which sits under NetworkError, so a bare except AuthenticationError won't catch it and it needs its own branch. So don't work through "the most common causes" one by one — dig the code out first, then follow the line that matches it. 50120 "insufficient permission" has to be pulled out on its own: it isn't in that 401 pile. Per the official error-code table it comes back as HTTP 200 and is identified by the code in the body, so at the protocol level the request "succeeded" — going by the status code alone, you can't tell anything went wrong at all.

• 50113 Invalid signature: look at the signing step. How the signature payload is assembled (request method, request path, request body), whether the key used for the HMAC really is the secret, whether you ran HMAC-SHA256 and then Base64. With ccxt the library does the signing, so at that point suspect a miscopied secret first.
• 50105 wrong Passphrase (50104 = not supplied): look only at the passphrase. The password field in ccxt must hold the Passphrase you set when creating the Key—not your login password, and not the secret; if you can't recall it, the only way out is to delete the Key and recreate it.
• 50102 / 50112 timestamp problems: look only at the clock. Per the official docs, a request timestamp more than 30 seconds away from server time is rejected. Turn on NTP auto-sync, and on long-running machines check periodically that it really is syncing. In ccxt, 50102 raises InvalidNonce: resync the clock in that branch before retrying, and keep a final BaseError catch-all.
• 50111 Invalid OK-ACCESS-KEY: look at the apiKey itself — a leading or trailing space from pasting, a dropped character, or a Key that's been deleted.
• 50101 APIKey does not match current environment: the Key is fine, the environment isn't — a demo Key sent without set_sandbox_mode(True) (no demo header on the request, so it's treated as live), or a live Key sent with it on. Line the Key and the switch up, then print okx.headers.get('x-simulated-trading') as a self-check; on demo it should be 1. In ccxt this one raises AuthenticationError too.
• 50110 IP not on the whitelist: look at the network egress, not at the credentials. See the "IP whitelist" section below.
• 50120 insufficient permission (HTTP 200): the credentials are all fine, this Key simply doesn't have the box ticked. It never shows up as a 401 — the only way to see it is to read the code in the body, so don't write your handling as just if status == 401. See "Permission denied" below.

One more thing worth mentioning: OKX's msg text will sometimes name the exact header that's at fault, so write it down verbatim alongside the code — far quicker than guessing from impressions.

Permission denied

The classic symptom is "can check the balance, can't place orders." Checking the balance uses the read permission; placing orders uses the trade permission, and they're granted separately. Go back to API management on OKX, find this Key, and add "Trade"—no need to recreate. And if you happened to tick withdrawal—don't leave it on; a quant Key should never have withdrawal permission. Also, don't read "trade permission" too narrowly: by OKX's own definition it covers not just placing and cancelling orders but funding transfers and part of the account settings too, so there's no need to tick withdrawal just to move funds between your own accounts.

IP whitelist (50110)

This error says "the outbound IP you're on right now isn't on this Key's list," so troubleshooting starts at the network egress, not at the credentials:

• Find out what your current outbound IP is first and check it against the list you filled in for this Key in the dashboard. Note that it's the outbound IP: with a proxy on, through a corporate gateway, or after your home broadband has redialled, the egress may well not be the one you think.
• If the outbound IP is unstable, the fix is to pin the egress down, not to take the lock off: move the strategy onto a machine with a fixed IP, or update the whitelist on a controlled schedule when the egress genuinely does change. OKX allows up to 20 IPs per Key, IPv4, IPv6 and CIDR ranges included, so leaving yourself headroom isn't hard.
• While debugging, use a read-only Key or a demo Key rather than repeatedly testing with the main key that carries trade permission.
• Don't make "remove the whitelist" a routine troubleshooting move. Officially, binding an IP is strongly recommended rather than mandatory, but one rule is worth remembering: a Key with no IP bound that carries trade or withdraw permission expires after 14 days of inactivity — so an unbound Key isn't only riskier, it may also quietly stop working one day. Demo Keys are not subject to that expiry rule, which is one more reason to debug with one.

Insufficient balance

Beyond the literal "not enough money," there's a sneaky cause: OKX has different accounts (funding, trading, etc.), and your money may not be in the one used for ordering. Confirm the funds have been transferred to the trading account. On the demo, if the virtual funds run out, just reset them on the demo interface—another upside of practicing on the demo first, where trial and error costs no real money.

Symbol / precision class

Spot pairs in ccxt are uniformly UPPER/UPPER with a forward slash, like BTC/USDT. Writing it as BTCUSDT, lowercase, or in a futures format all throws errors. If the amount is too small or the precision is off, use load_markets() to check the pair's minimum order size and precision and go by what it requires. There's a full order example for this in our API quant intro.

Rate limits and backoff retry

The rate limit (50011 / Too Many Requests) is one script writers easily run into and should defend against ahead of time. It's not that you did something wrong—your requests were just too dense and tripped the exchange's protection. Handle it in two layers:

Layer one: turn on ccxt's built-in rate limiter. Add 'enableRateLimit': True at init, and ccxt will automatically insert reasonable gaps between requests. For most cases this step alone is enough:

okx = ccxt.okx({
    'apiKey':   'YOUR_apiKey',
    'secret':   'YOUR_secret',
    'password': 'YOUR_Passphrase',
    'enableRateLimit': True,   # auto rate-limit, turn this on first
})

Layer two: add exponential backoff retry. If your strategy really does send dense requests at certain moments (like polling many pairs at once), auto rate-limiting alone may still occasionally hit. Wrap key requests in a retry layer then: wait 1 second on the first hit and retry, then 2, then 4, stretching it out, and give up with an error after enough hits.

import ccxt, time

def with_retry(fn, max_tries=5):
    delay = 1
    for i in range(max_tries):
        try:
            return fn()
        except ccxt.RateLimitExceeded:
            print(f'Rate limited, attempt {i+1}, waiting {delay}s before retry')
            time.sleep(delay)
            delay *= 2          # exponential backoff: 1 → 2 → 4 → 8 ...
    raise RuntimeError('Still rate limited after retries, giving up')

# Usage: drop the call that gets rate limited in here
ticker = with_retry(lambda: okx.fetch_ticker('BTC/USDT'))
print(ticker['last'])

A cautionary counter-example: don't write a while True: that hammers the endpoint immediately with no delay in between. That kind of loop fires off dozens to hundreds of requests a second and instantly hits the rate limit. Any high-frequency loop needs gaps.

A common gotcha

FAQ

Clear the error-troubleshooting hurdle and your script stops freezing up at every turn. The next thing worth your time is writing risk control into the code—scarier than an error is a script that doesn't error but keeps placing the wrong orders. And don't forget to run new code on the demo account first—debugging there costs no real money.