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.InvalidNonce as e:
    print('Zaman damgası süresi doldu (50102), saati düzeltip tekrar dene:', e)
except ccxt.AuthenticationError as e:
    print('Kimlik doğrulama başarısız, neye bakacağına karar vermeden önce hatadaki code degerine bak:', 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. Tablodaki hata kodlarının anlamları 2026-09'da, OKX API v5 dokümanının Error Code bölümü esas alınarak doğrulanmıştı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. Kimlik doğrulama grubunda özellikle code'a göre dallanmak gerekir: ikisi de «bağlanamıyorum» gibi görünse de 50113 ile 50105'te bakılacak yer tamamen farklıdı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ü (50102 / 50105 / 50110 / 50111 / 50112 / 50113) ve yetki türü (50120)

Kimlik doğrulama hataları HTTP katmanında istisnasız 401'dir; ccxt'te çoğu AuthenticationError fırlatır (50110'un fırlattığı PermissionDenied da onun alt sınıfıdır). İstisna 50102, yani zaman damgası süresinin dolması: ccxt'in 2026-09 tarihli ana dal kaynak koduna göre InvalidNonce'a eşlenir, bu da NetworkError kolundadır; yalnızca except AuthenticationError yazarsan onu yakalayamazsın, ayrı bir dal gerekir. O yüzden «en sık nedenler»i tek tek denemeye kalkma — önce code'u çıkar, sonra ona karşılık gelen satırı izle. 50120 «yetki yetersiz» ayrı tutulmalı: o, 401 yığınının içinde değildir. Resmî hata kodu tablosuna göre HTTP 200 ile döner ve gövdedeki code ile ayırt edilir; yani istek protokol düzeyinde «başarılı»dır, sadece durum koduna bakarak bir şeyin ters gittiğini hiç göremezsin.

• 50113 Invalid signature: imza adımına bak. İmza metninin birleştirilmesi (istek yöntemi, istek yolu, istek gövdesi), HMAC için kullanılan anahtarın secret olup olmadığı, HMAC-SHA256 sonrası Base64 alınıp alınmadığı. ccxt kullanıyorsan imzayı kütüphane atar; bu durumda önce secret'ın yanlış kopyalandığından şüphelen.
• 50105 Passphrase yanlış (50104 ise hiç doldurulmamış): yalnızca parolaya bak. 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. Hatırlamıyorsan tek yol Key'i silip yeniden oluşturmaktır.
• 50102 / 50112 zaman damgası sorunu: yalnızca saate bak. Resmî dokümana göre istek zaman damgası ile sunucu saati arasındaki fark 30 saniyeyi aşarsa istek reddedilir. NTP otomatik saat ayarını aç; uzun süre çalışan makinelerde gerçekten senkronize olduğunu ara ara doğrula. ccxt'te 50102 InvalidNonce fırlatır: o dalda saati düzeltip yeniden dene, en sona da bir BaseError yakalayıcısı bırak.
• 50111 Invalid OK-ACCESS-KEY: apiKey'in kendisine bak — yapıştırırken baş-sonda boşluk kalmış, karakter eksilmiş, Key silinmiş ya da gerçek hesap Key'i demoya (veya tersi) bağlanmış olabilir.
• 50110 IP beyaz listede değil: kimlik bilgilerine değil, ağ çıkışına bak. Aşağıdaki «IP beyaz listesi» bölümüne bak.
• 50120 yetki yetersiz (HTTP 200): bilgilerin hepsi doğru, yalnızca bu Key'de ilgili yetki işaretli değil. Hiçbir zaman 401 biçiminde görünmez; onu ancak gövdedeki code'u okuyarak fark edersin — bu yüzden kontrol mantığını sadece if status == 401 diye yazma. Aşağıdaki «Yetki yetersiz»e bak.

Bu arada: OKX'in msg metni bazen sorunun hangi header'da olduğunu doğrudan söyler; onu code ile birlikte olduğu gibi not almak, izlenime dayanarak tahmin etmekten çok daha hızlıdır.

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. Ayrıca «işlem yetkisi»ni fazla dar düşünme: OKX belgelerindeki tanıma göre emir verip iptal etmenin yanında fon transferini ve bir kısım hesap ayarını da kapsar; yani hesaplar arası transfer yapabilmek için çekimi işaretlemeye gerek yoktur.

IP beyaz listesi (50110)

Bu hata «şu anki çıkış IP'n bu Key'in listesinde değil» demektir; dolayısıyla araştırma kimlik bilgilerinden değil, ağ çıkışından başlar:

• Önce mevcut çıkış IP'ni öğren ve panelde bu Key için doldurduğun listeyle tek tek karşılaştır. Dikkat, söz konusu olan çıkış IP'sidir: proxy açıksan, şirket ağ geçidinden geçiyorsan ya da evdeki internet yeniden bağlandıysa çıkış sandığın IP olmayabilir.
• Çıkış IP'si oynaksa çözüm yönü, kilidi sökmek değil çıkışı sabitlemektir: stratejiyi sabit IP'li bir makineye taşı ya da çıkış gerçekten değiştiğinde beyaz listeyi düzenli bir ritimle güncelle. OKX tarafında her Key'e en fazla 20 IP bağlanabilir, IPv4/IPv6 ve ağ bloğu desteklenir; pay bırakmak zor değil.
• Hata ayıklama aşamasında salt okunur Key ya da demo Key kullan, işlem yetkisi olan asıl Key'le defalarca deneme yapma.
• «Beyaz listeyi kaldırmak»ı rutin bir sorun giderme hamlesi yapma. Resmî tutum, IP bağlamayı zorunlu değil şiddetle tavsiye edilen bir adım saymaktır; ama akılda tutulması gereken bir kural var: IP bağlanmamış, üstelik trade ya da withdraw yetkisi taşıyan bir Key 14 gün hareketsiz kalırsa süresi dolar — yani IP bağlanmamış bir Key hem daha riskli, hem bir gün kendiliğinden geçersizleşebilir. Demo Key'ler bu süre dolma kuralına tabi değildir; hata ayıklamayı onunla yapmanın bir nedeni de budur.

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.

Sık düşülen bir hız sınırı tuzağı

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.