Поширені помилки OKX API та чек-лист діагностики: виправляй за цією таблицею

Хто пише квант-скрипти, у вісьмох випадках із десяти застрягає не на стратегії, а на одному червоному рядку помилки: скрипт запускається, у термінал вилазить незрозумілий code з англійським текстом — і людина впадає в ступор. Хороша новина: помилок OKX API лише кілька частих різновидів, і коли розумієш, як кожна виглядає й якій причині відповідає, діагностика стає набагато швидшою.

У цій статті ми (команда MeowQuant) звели в чек-лист помилки, на які наступали самі й які раз по раз бачили у спільнотах. Ядро — таблиця кодів помилок: щось зламалося — спершу знайди в таблиці за кодом чи ключовим словом, а потім дивись відповідну покрокову діагностику нижче. Прочитавши, ти зможеш розв'язувати більшість помилок самотужки за лічені хвилини, а не тупити в червоний текст.

Спершу навчись читати помилку: code + msg

Перший крок діагностики — зрозуміти саму помилку. Коли інтерфейс OKX повертає помилку, у ній три речі:

• HTTP-статус: найгрубший шар, наприклад 401 (проблема автентифікації), 429 (забагато запитів), 400 (проблема в самому запиті).
• code: власний числовий код помилки OKX, найточніше вказує на тип проблеми. Це твоя головна опора в діагностиці.
• msg: текстовий опис, допомагає підтвердити напрямок, інколи прямо вказує, яке поле хибне.

Якщо ти на ccxt, він загортає ці сирі помилки в зручніші типи винятків: проблему автентифікації кидає як AuthenticationError, ліміт частоти — RateLimitExceeded, брак коштів — InsufficientFunds. У тексті винятку зазвичай є й оригінальні code та msg від OKX. Гарна звичка — обгорнути все у try/except і чітко вивести:

import ccxt

okx = ccxt.okx({
    'apiKey':   'твій_apiKey',
    'secret':   'твій_secret',
    'password': 'твій_Passphrase',
    'enableRateLimit': True,
})

try:
    balance = okx.fetch_balance()
    print('USDT доступно:', balance['USDT']['free'])
except ccxt.AuthenticationError as e:
    print('Автентифікація не вдалася, перевір три облікові дані й системний час:', e)
except ccxt.RateLimitExceeded as e:
    print('Спрацював ліміт частоти, сповільни запити:', e)
except ccxt.BaseError as e:
    print('Інша помилка, дивись оригінальні code/msg:', e)

Запиши той рядок code й msg із винятку дослівно, звір із таблицею нижче — і майже завжди локалізуєш, до якого класу проблем це належить.

Таблиця частих помилок

Ця таблиця охоплює кілька помилок, на які новачки наштовхуються найчастіше. Коди наводимо за чинною документацією OKX API v5 (OKX інколи коригує значення кодів; якщо щось не збігається — орієнтуйся на текст msg і офіційну документацію), а суть — поєднати «причину → як виправити».

Покрокова діагностика й виправлення

Таблиця дає напрямок, цей розділ — деталі. Обери ту помилку, на яку наштовхнувся, і дивись далі.

Автентифікаційні (Invalid sign / API key недійсний / помилка Passphrase)

Це зона найбільших провалів новачків; перевіряй у цьому порядку — влучатимеш найчастіше:

• Спершу перевір Passphrase. У поле password у ccxt має бути вписано саме той Passphrase, який ти задав при створенні ключа — не пароль для входу й не secret. На цей пункт припадає більша половина провалів автентифікації.
• Потім перевір apiKey / secret на помилку копіювання. Часто при вставці на початку/в кінці з'являються зайві пробіли або зникають один-два символи. Найнадійніше — скопіювати з кабінету заново.
• Перевір ще й системний час. Неточний час робить мітку підпису застарілою, проявляється теж як помилка автентифікації. Увімкни корекцію через NTP.

Недостатньо прав

Типовий симптом — «можу перевірити баланс, не можу виставити ордер». Баланс іде через право читання, ордер — через право торгівлі, вони надаються окремо. Зайди в керування API в кабінеті OKX, знайди цей ключ і додай «Торгівлю» — перестворювати не треба. Якщо мимохідь ставив виведення — прибери: квант-ключ ніколи не повинен мати права виведення.

Недостатньо коштів

Окрім буквального браку грошей, є й прихована причина: у OKX різні рахунки (фінансовий, торговий тощо), і твої кошти можуть бути не на тому, з якого виставляється ордер. Переконайся, що кошти переведено на торговий рахунок. На демо — якщо віртуальні кошти скінчилися, скинь їх в інтерфейсі демо. Це теж перевага того, щоб спершу практикуватися на демо — проби й помилки не коштують справжніх грошей.

symbol / точність

Спотові пари в ccxt — це ВЕЛИКІ/ВЕЛИКІ з прямим слешем, наприклад BTC/USDT. Напишеш BTCUSDT, маленькими чи у ф'ючерсному форматі — буде помилка. Кількість надто мала або точність невірна — через load_markets() подивись мінімальний обсяг і точність для пари й роби за вимогою. Повний приклад виставлення ордера є в нашій статті Квант на OKX API.

Ліміт частоти й повтор із відкатом

Ліміт частоти (50011 / Too Many Requests) — те, на що скриптери впираються найчастіше і що варто запобігати наперед. Це не означає, що ти щось зробив не так, — просто надто щільні запити спрацювали на захист біржі. Обробляється у два шари:

Шар перший: увімкни вбудоване обмеження швидкості ccxt. При ініціалізації додай 'enableRateLimit': True, ccxt сам уставлятиме розумні паузи між запитами, і в більшості випадків цього кроку достатньо:

okx = ccxt.okx({
    'apiKey':   'твій_apiKey',
    'secret':   'твій_secret',
    'password': 'твій_Passphrase',
    'enableRateLimit': True,   # автообмеження швидкості, вмикай одразу
})

Шар другий: додай повтор з експоненційним відкатом. Якщо твоя стратегія в певні моменти справді шле дуже щільно (наприклад, одночасно опитує багато пар), самого автообмеження може бракувати, і ти інколи впиратимешся. Тоді обгорни ключові запити шаром повтору: уперся раз — чекай 1 с і повтори, ще раз — 2 с, 4 с, поступово збільшуючи, а після кількох спроб — здавайся з помилкою.

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'Ліміт частоти, спроба {i+1}, чекаю {delay}с і повторюю')
            time.sleep(delay)
            delay *= 2          # експоненційний відкат: 1 → 2 → 4 → 8 ...
    raise RuntimeError('Кілька повторів — усе ще ліміт частоти, здаюся')

# Вжиток: кидай сюди виклик, який упирається в ліміт
ticker = with_retry(lambda: okx.fetch_ticker('BTC/USDT'))
print(ticker['last'])

Негативний приклад: не пиши while True:, де одразу б'ється по інтерфейсу без жодної затримки. Такий цикл за секунду випустить десятки-сотні запитів, миттєво впреться в ліміт, а у важких випадках весь ключ ненадовго обмежать. У будь-якому частому циклі лишай паузи.

На практиці: наш власний промах

Поширені запитання

Коли пройдеш цей етап діагностики, твій скрипт перестане застрягати на дрібницях. Далі варто витратити час на те, щоб вписати ризик-менеджмент у код — страшніше за помилку те, коли скрипт без помилок безперервно виставляє хибні ордери. І не забувай: новий код спершу кидай у демо, діагностика не коштуватиме справжніх грошей.