OKX API yaygın hataları ve sorun giderme listesi: bu tabloya bakıp düzelt

Algo betiği yazanların onda dokuzu stratejide değil, kırmızı bir hata satırında takılır: betik çalışır, terminale anlaşılmaz bir code ve İngilizce yığını düşer, insan donar kalır. İyi haber şu ki OKX API'nin hataları yalnızca birkaç sık türden ibaret; her birinin neye benzediğini, hangi nedene karşılık geldiğini bilince sorun giderme çok daha hızlı olur.

Bu yazıda biz (MeowQuant editör ekibi) kendi başımıza gelen ve toplulukta defalarca gördüğümüz hataları bir listede topladık; çekirdeği bir hata kodu eşleştirme tablosu — bir sorun çıktığında önce tabloda hata kodu ya da anahtar kelimeyle yerini bul, sonra altındaki madde madde sorun gidermeye bak. Okuyunca çoğu hatayı kırmızı yazıya bakakalmadan birkaç dakikada kendin çözebilmelisin.

Önce hatayı okumayı öğren: code + msg

Hata gidermenin ilk adımı, hatanın kendisini anlamaktır. OKX arayüzü hata verince üç bilgi döndürür:

• HTTP durum kodu: en kaba katman, örneğin 401 (kimlik doğrulama sorunu), 429 (çok fazla istek), 400 (isteğin kendisinde sorun).
• code: OKX'in kendi sayısal hata kodu, sorun türünü en kesin gösterir. Sorun gidermenin ana dayanağı budur.
• msg: bir metin açıklaması, yönü doğrulamana yardım eder, bazen doğrudan hangi alanın hatalı olduğunu söyler.

ccxt kullanıyorsan bu ham hataları daha okunaklı istisna türlerine sarar; örneğin kimlik doğrulama sorununda AuthenticationError, istek sınırında RateLimitExceeded, bakiye yetersizliğinde InsufficientFunds fırlatır. İstisna mesajında da genelde OKX'in ham code ve msg'si bulunur. İyi bir alışkanlık, bunları try/except ile net yazdırmaktır:

import ccxt

okx = ccxt.okx({
    'apiKey':   'senin_apiKey',
    'secret':   'senin_secret',
    'password': 'senin_Passphrase',
    'enableRateLimit': True,
})

try:
    balance = okx.fetch_balance()
    print('USDT kullanılabilir:', balance['USDT']['free'])
except ccxt.AuthenticationError as e:
    print('Kimlik doğrulama başarısız, üç bilgiyi ve sistem saatini kontrol et:', e)
except ccxt.RateLimitExceeded as e:
    print('İstek sınırına takıldı, istekleri yavaşlat:', e)
except ccxt.BaseError as e:
    print('Başka hata, ham code/msg degerine bak:', e)

İstisnadaki o code ve msg'yi olduğu gibi not al, aşağıdaki tabloyla karşılaştır, hangi tür soruna düştüğünü çoğunlukla bulabilirsin.

Sık hatalar eşleştirme tablosu

Aşağıdaki tablo yeni başlayanların en sık çarptığı birkaç hatayı kapsar. Hata kodları OKX'in güncel API v5 dokümanındaki değerleri esas alır (OKX zaman zaman kod değerlerini değiştirebilir, uymayanla karşılaşırsan msg metnini ve resmî dokümanı esas al); önemli olan «neden → nasıl düzeltilir» eşleşmesini doğru kurmaktır.

Madde madde nasıl düzeltilir

Tablo yön verir, bu bölüm ayrıntı verir. Çarptığın maddeyi seçip aşağı bak.

Kimlik doğrulama türü (Invalid sign / geçersiz API key / Passphrase hatası)

Bu yeni başlayan hatalarının en yoğun bölgesidir; aşağıdaki sırayla kontrol et, isabet oranı en yüksek budur:

• Önce Passphrase'i kontrol et. ccxt'teki password alanına yazılması gereken, Key'i oluştururken belirlediğin o Passphrase dizisidir; giriş şifresi değil, secret de değil. Bu madde kimlik doğrulama hatalarının yarısından fazlasını kapsar.
• Sonra apiKey / secret yanlış kopyalanmış mı bak. Sık olan, yapıştırırken baş-son fazladan boşluk ya da bir iki eksik karakterdir. Panelden yeniden kopyalamak en sağlamı.
• Sistem saatini de kontrol et. Saat yanlış olunca imza zaman damgası dolar, belirtisi yine kimlik doğrulama hatasıdır. NTP saat ayarını aç.

Yetki yetersiz

Tipik belirti «bakiye sorgulanabiliyor, emir verilemiyor»dur. Bakiye sorgulamak okuma yetkisi, emir vermek işlem yetkisidir; ikisi ayrı verilir. OKX panelindeki API yönetimine dönüp bu Key'i bul, «İşlem»i ekle yeter, yeniden oluşturmaya gerek yok. Eğer çekim de işaretlediysen, bırakma — algo çalıştıran Key'de çekim yetkisi asla açılmaz.

Yetersiz bakiye

Lafzi anlamda para yetmemesi dışında gizli bir neden daha var: OKX'in farklı hesapları (fon hesabı, işlem hesabı vb.) vardır, paran emir verilen hesapta olmayabilir. Paranın işlem hesabına aktarıldığını doğrula. Demo hesapta sanal sermaye biterse demo arayüzünden sıfırlamak yeter — bu da önce demo hesapta alıştırma yapmanın faydasıdır, deneme yanılma gerçek para harcamaz.

symbol / hassasiyet türü

ccxt'te spot işlem çiftleri tek tip BÜYÜK/BÜYÜK ve düz eğik çizgilidir, örneğin BTC/USDT. BTCUSDT, küçük harf ya da vadeli biçim hata verir. Miktar çok küçük ya da hassasiyet yanlışsa load_markets() ile bu çiftin en düşük emir miktarına ve hassasiyetine bakıp istenene göre doldur. Bu konunun eksiksiz emir örneği API'ye giriş yazımızda var.

İstek sınırı ve geri çekilmeli yeniden deneme

İstek sınırı (50011 / Too Many Requests), betikçilerin en sık çarptığı ve en çok önceden önlemesi gereken hata türüdür. Yanlış bir şey yapmandan değil, isteklerin çok sık olması üzerine borsanın korumasının devreye girmesinden kaynaklanır. İki katmanda ele al:

Birinci katman: ccxt'in kendi hız sınırlamasını aç. Başlatırken 'enableRateLimit': True ekle, ccxt istekler arasına makul aralık koyar; çoğu durumda bu adım yeter:

okx = ccxt.okx({
    'apiKey':   'senin_apiKey',
    'secret':   'senin_secret',
    'password': 'senin_Passphrase',
    'enableRateLimit': True,   # Otomatik hız sınırlama, önce aç
})

İkinci katman: üstel geri çekilmeli yeniden deneme ekle. Stratejin bazı anlarda gerçekten çok sık istek yapıyorsa (örneğin aynı anda çok çiftin verisini çekiyorsa), tek başına otomatik hız sınırlama yine ara sıra çarpabilir. Bu durumda kritik isteğe bir yeniden deneme katmanı sar: bir çarpışta 1 saniye bekleyip tekrar dene, sonra 2, 4 saniye, kademe kademe uzat, yeterince çarpınca vazgeçip hata fırlat.

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'İstek sınırı, {i+1}. deneme, {delay}s bekleyip tekrar')
            time.sleep(delay)
            delay *= 2          # Üstel geri çekilme: 1 → 2 → 4 → 8 ...
    raise RuntimeError('Birçok denemeye rağmen istek sınırı, vazgeçildi')

# Kullanım: istek sınırına takılacak çağrıyı buna ver
ticker = with_retry(lambda: okx.fetch_ticker('BTC/USDT'))
print(ticker['last'])

Bir kötü örnek: while True: içine hemen API çağrısı koyup arasına hiç gecikme koymama. Böyle bir döngü bir saniyede onlarca yüzlerce istek atar, anında istek sınırına çarpar, kötü durumda tüm Key kısa süre kısıtlanır. Her yüksek frekanslı döngüde mutlaka aralık bırak.

Test: bizim düştüğümüz bir tuzak

Sık sorulan sorular

Hata giderme eşiğini aşınca betiğin durup dururken kilitlenmez. Sırada vakit ayırmaya değer olan şey, risk yönetimini koda yazmaktır — hatadan daha korkutucusu, betiğin hata vermeden sürekli yanlış emir vermesidir. Yeni kodu önce demo hesaba atmayı da unutma, hata gidermek gerçek para harcamaz.