Kripto piyasa API'sini rate limite takılmadan sorgulama: ETag, gzip, filtreler ve 429 sonrası yeniden deneme
Kısaca
- Bir API'nin genellikle üç limiti vardır: saniyedeki istek sayısı, dönem başına çağrı kotası ve indirme hacmi. Genesis API'de bu, saniyede 1 ila 15 istek, 30 günde 500K ila 10M çağrı ve anahtar başına 10 saniyede 60 MB sıkıştırılmış veridir.
- Sorgu aralığını
meta.freshness_secdeğerine göre belirleyin: daha sık sorgulamak aynı anlık görüntüyü döndürür.If-None-Matchtekrarı ücretsiz bir304'e çevirir, gzip ve filtreler trafiği azaltır, coin başına istek yerine tek bir tam veri seti çağrıdan tasarruf ettirir. 429ve503yanıtlarınıRetry-Aftersaniye sonra veya bu başlık yoksa üstel geri çekilme ile rastgele jitter kullanarak yeniden deneyin. İstemci tarafındaki token bucket hızınızı limitin altında tutar,X-RateLimit-*veX-Quota-*başlıkları ise kalan payı gösterir.
Bir API'yi 429 hatası almadan sorgulamak için istekleri aynı anda üç limite göre şekillendirin: saniyedeki istek sayısı, dönem kotası ve indirdiğiniz veri hacmi. Beş teknik bunu karşılar: verinin yenilenme süresinden kısa olmayan bir aralık, ETag ile koşullu istekler, gzip sıkıştırma, büyük indirmeler yerine filtreler ve sunucunun istediği beklemeden sonra yeniden deneme. Aşağıdaki sayılar ve kod, kripto piyasa verileri için bir REST API olan Genesis API içindir, ancak teknikler borsa API'leri dahil her HTTP API'si için geçerlidir.
Üç API limiti: saniyedeki istek, kota ve hacim
Saniye başına rate limit ani yüklenmeleri yakalar: aynı anda gönderilen bir istek grubunu. Kota, tüm dönem boyunca ortalama hızınızı yakalar; hacim limiti ise istek az olsa bile ağır indirmeleri yakalar.
| Limit | Neyi sayar | Genesis API | Limit aşılınca |
|---|---|---|---|
| Saniyedeki istek | 304 ve hatalar dahil her istek | Trial'da 1, Start'ta 2, Pro'da 5, Max'te 15 | 429 rate_limited, Retry-After: 1 |
| Dönem kotası | Yalnızca 200 yanıtları | 30 günde 500K, 2M, 5M, 10M çağrı | 429 rate_limited, kota sıfırlanana kadar Retry-After |
| İndirme hacmi | 64 KB ve üzeri sıkıştırılmış yanıtlar | Her planda anahtar başına 10 saniyede 60 MB | Pencere bitene kadar 429 download_limited |
Genesis API, limiti aşan istekler için asla ücret almaz: 429 kota harcamaz ve hiçbir maliyeti yoktur. Tüm kurallar Genesis API limitleri rehberinde ve dokümantasyonun Planlar ve limitler bölümünde yer alır.
Borsa API'leri daha karmaşık olabilir. Binance, istek ağırlığını IP adresi başına sayar ve her endpoint'in kendi ağırlığı vardır. 429 sonrası istek göndermeye devam eden istemci, 418 durumuyla otomatik IP yasağı alır; tekrar edenler daha uzun yasaklanır (Binance dokümantasyonu).
Sorgu aralığı: 30 günde kaç çağrı harcarsınız
Verinin yenilendiğinden daha sık sorgulamak tekrardan başka bir şey getirmez. Genesis Arbitrage çekirdeği veriyi her saniye yeniler, planınızın API çıktısı ise her meta.freshness_sec saniyede bir yenilenir: Trial'da 60, Start'ta 30, Pro'da 10 ve Max'te 5. Bu, planınızın veri tazeliğidir ve sorgu aralığınızın alt sınırıdır. Genesis API'de WebSocket veya webhook yoktur, veriyi REST üzerinden sorgulayarak alırsınız.
Örnek (açıklayıcı): Start planındaki bir bot — ayda 50 $, 2M çağrı, saniyede 2 istek, 30 sn tazelik — dört endpoint'i sorgular: /arbitrage/spot-spot, /arbitrage/spot-futures, /funding/spread ve /market/open-interest.
| Aralık | 30 günde çağrı | Start kotasındaki pay | Aynı anlık görüntünün tekrarı |
|---|---|---|---|
| 60 sn | 172.800 | %8,64 | yok |
| 30 sn | 345.600 | %17,28 | yok |
| 10 sn | 1.036.800 | %51,84 | 3 yanıtın 2'si |
| 5 sn | 2.073.600 | %103,68 | 6 yanıtın 5'i |
5 saniyede bir sorgulamak kotayı 29. günde tüketir: günde 4 × 86.400 / 5 = 69.120 çağrı ve 2.000.000 / 69.120 ≈ 28,9 gün. Her altı yanıttan beşi aynı meta.updated_at değerine sahip tek bir anlık görüntüyü tekrar eder ve If-None-Match olmadan her biri bir çağrıya mal olur.
30 saniyede bir sorguda ortalama hız 4 / 30 ≈ 0,13 istek/sn'dir. Ancak aynı anda gönderilen dört istek aynı saniyeye düşer ve ikisi 429 alır. 30 saniyeden taze veriye ihtiyacınız varsa çözüm, daha düşük freshness_sec değerine sahip bir plandır: Pro anlık görüntüyü her 10 saniyede, Max her 5 saniyede yeniler.
Koşullu istekler: ETag, If-None-Match ve 304
ETag, yanıtın sürüm etiketidir. İstemci onu saklar ve aynı URL'ye bir sonraki isteğinde If-None-Match başlığıyla geri gönderir; sürüm değişmediyse sunucu 304 Not Modified yanıtı verir. RFC 9110 uyarınca 304 başlıklardan sonra biter ve gövde taşımaz, yani kendi veri kopyanızı kullanırsınız.
Genesis API'de 304 kota harcamaz ama saniyedeki istek limitinde yine bir yer kaplar. Yalnızca filtresiz tam veri setleri etiket alır. coin, exchange, min_spread veya başka filtreli isteklerin yanıtları ile /orderbooks/book ve /orderbooks/coin/{coin} her istekte yeniden oluşturulur ve ETag olmadan gelir.
ETag, verinin sizin sorgu sıklığınızdan daha seyrek değiştiği yerde kotadan tasarruf ettirir. Spread'lerdeki etiket her anlık görüntüde değişir, bu yüzden freshness_sec başına bir kez sorguladığınızda neredeyse her yanıt 200 olur.
Pro'da örnek (açıklayıcı): fonlama analitiğinin günlük toplamları olan /funding/analytics/daily her saat yeniden oluşturulur; bir yıllık geçmiş biriktiğinde tam bölüm yaklaşık 12 MB gzip olur ve coin olmadan en fazla 300 saniyede bir sunulur. 300 saniyede bir sorgulamak 30 günde 2.592.000 / 300 = 8.640 istek eder. If-None-Match ile bölüm 30 × 24 = 720 kez indirilir, kalan 8.640 − 720 = 7.920 yanıt 304 olarak gelir.
Sonuç: 8.640 yerine 720 çağrı ve 104 GB yerine yaklaşık 8,6 GB trafik. 304 yanıtları tam indirme limitine sayılmaz.
Filtreler ve coin: neyin çağrıdan, neyin trafikten tasarruf ettirdiği
Filtre yanıtı küçültür ama çağrı sayısını değil: kota yanıtları sayar ve coin=BTC içeren bir istek tam veri seti kadar maliyetlidir. Bu yüzden seçim, önce hangisinin tükendiğine bağlıdır: çağrıların mı, trafiğin mi.
Start'ta örnek (açıklayıcı): bir bot beş coin için fonlamayı izler. 30 saniyede bir coin ile /funding/rates'e yapılan beş istek, 30 günde 5 × 86.400 = 432.000 çağrı eder, üstüne döngü başına beş istek saniyede 2 limitine karşı gelir. Coin'lerin kodda ayıklandığı tek bir tam /funding/rates ise 86.400 çağrıya mal olur, yani beş kat az, ayrıca ETag alır.
| Görev | Nasıl istenir | Neyi kazandırır |
|---|---|---|
| Tek veri setinden birkaç coin | If-None-Match ile tam veri seti, filtre kodda | Çağrı: birkaç yerine tek istek |
| Ağır bir bölümden tek coin | coin parametresi | Trafik ve hacim limiti |
| Eşiğin üstündeki satırlar | min_spread, min_volume | Trafik, ama her sorgu bir çağrıdır |
| Yavaş bir bölümün tamamı | If-None-Match ile tam veri seti | Çağrı ve trafik |
En ağır bölümler fonlama analitiğine aittir: tam özet yaklaşık 600 KB gzip, 7 günlük ödemeler yaklaşık 1 MB ve günlük toplamlar 12 MB'a kadardır (Fonlama endpoint'leri). coin ile tek coin'lik dilim, tam indirme limitinin dışındadır; bu limit özet ve ödemeler için 60 saniyede bir, günlük toplamlar için 300 saniyede birdir.
Gzip sıkıştırma
Sıkıştırma, hatta giden bayt sayısını azaltır. İstemci bunu Accept-Encoding: gzip ile ister, sunucu sıkıştırılmış gövde ve Content-Encoding: gzip başlığıyla yanıt verir. Python'ın requests kütüphanesi Accept-Encoding'e gzip ekler ve yanıtı kendisi açar; curl aynısını --compressed ile yapar.
Genesis API'de sıkıştırma bir limite bağlıdır: indirme hacmi sıkıştırılmış veriyle, anahtar başına 10 saniyede 60 MB olarak sayılır ve 64 KB'ın altındaki yanıtlar sayılmaz. Tam veri setleri ve büyük yanıtlar, istemci istediğinde gzip'li gelir (Genesis API yanıtları ve hataları). Ağ üzerinden gerçekte kaç gövde baytı geçtiğini görmek için curl'ün size_download değişkenini kullanın:
# body bytes on the wire with and without gzip; each request is a call
URL="https://api.genesisarbitrage.com/v1/funding/rates"
curl -s -o /dev/null --compressed -w "gzip: %{size_download}\n" \
-H "X-API-Key: $GENESIS_API_KEY" "$URL"
curl -s -o /dev/null -w "uncompressed: %{size_download}\n" \
-H "X-API-Key: $GENESIS_API_KEY" "$URL"
429 sonrası yeniden deneme: Retry-After ve jitter'lı geri çekilme
HTTP 429 Too Many Requests, limiti aşan istemciye sunucunun yanıtıdır. RFC 6585 uyarınca yanıt Retry-After başlığı taşıyabilir, RFC 9110 uyarınca değeri saniye sayısı veya bir tarihtir. Genesis API her 429 ve 503 ile saniye cinsinden Retry-After gönderir.
Beklemeden yapılan yeniden deneme neredeyse her zaman aynı hatayı alır ve saniyelik pencerede bir yer daha kaplar. Retry-After varsa sunucunun istediği kadar bekleyin. Yoksa her başarısızlıktan sonra katlanarak uzayan süre bekleyin: en fazla 1, 2, 4, 8 saniye.
Jitter, beklemeye eklenen rastgele süredir ve çok sayıda istemci olduğunda önemlidir: o olmadan aynı saniyede hata alan herkes aynı saniyede yeniden dener. backoff fonksiyonu sıfırla mevcut basamak arasında rastgele bir bekleme seçer ve Retry-After değerine bir saniyenin kesri ekler. fetch, 429, 500 ve 503 yanıtlarını yeniden dener ve bekleme 10 dakikadan uzunsa durur: tükenmiş bir kota böyle görünür.
import os
import random
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session() # reuses the TCP connection, gzip is on
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # path -> (ETag, data): full datasets only
def backoff(attempt, retry_after=None, cap=60.0):
"""Pause before a retry, in seconds."""
if retry_after and retry_after.isdigit():
return int(retry_after) + random.uniform(0, 1)
return random.uniform(0, min(cap, 2 ** attempt))
def fetch(path, params=None, tries=5):
"""GET from the API: returns (data, response headers)."""
for attempt in range(tries):
tag = None if params else cache.get(path, (None,))[0]
try:
r = api.get(BASE + path, params=params, timeout=15,
headers={"If-None-Match": tag} if tag else {})
except (requests.ConnectionError, requests.Timeout):
time.sleep(backoff(attempt))
continue
if r.status_code == 304: # same snapshot, no quota used
return cache[path][1], r.headers
if r.status_code in (429, 500, 503):
wait = backoff(attempt, r.headers.get("Retry-After"))
if wait > 600: # this is what an exhausted quota looks like
raise RuntimeError(f"quota resets in {wait:.0f} s")
time.sleep(wait)
continue
r.raise_for_status() # 400, 401, 403, 404, 410: do not retry
data = r.json()["data"]
if not params and "ETag" in r.headers:
cache[path] = (r.headers["ETag"], data)
return data, r.headers
raise RuntimeError(f"{path}: no response after {tries} tries")
| Yanıt | Bekleme | Yeniden deneme |
|---|---|---|
429 rate_limited, saniyelik | Retry-After: 1 artı saniyenin bir kesri | Evet |
429 rate_limited, kota | Kota sıfırlanana kadar, günler sürebilir | Hayır |
429 download_limited | Retry-After, pencere bitene kadar | Evet, daha dar isteklerle |
503 snapshot_not_ready | Retry-After | Evet |
500, zaman aşımı, kopan bağlantı | Jitter'lı üstel | Evet |
400, 401, 403, 404, 410 | — | Hayır, isteği düzeltin |
Tükenmiş kotayı saniyelik limitten Retry-After ile ayırt edersiniz: bir saniyeye karşı sıfırlanmaya kadar saatler veya günler; yanıt gövdesinde ayrıca Monthly call quota exceeded. yazar. Hata kodları ve gövdeleri dokümantasyonun Hatalar bölümündedir.
İstemci tarafı rate limiter: token bucket
Yeniden deneme bir 429'la ilgilenir; istemci tarafı limiter ise onu önler. Token bucket şöyle çalışır: token'lar saniyede rate hızıyla gelir, her istek bir token alır ve boş kova sizi bekletir. Kapasite olan burst, bekleme olmadan art arda kaç isteğin çıkabileceğini belirler.
import time
class TokenBucket:
"""At most rate requests per second, up to burst back to back."""
def __init__(self, rate, burst=1):
self.rate, self.burst = rate, burst
self.tokens = float(burst)
self.last = time.monotonic()
def take(self):
while True:
now = time.monotonic()
self.tokens = min(self.burst, self.tokens
+ (now - self.last) * self.rate)
self.last = now
if self.tokens >= 1:
self.tokens -= 1
return
time.sleep((1 - self.tokens) / self.rate)
Limiti /account/usage içindeki rps_limit alanından (Kullanım bölümü) veya X-RateLimit-Limit başlığından alın. Hızı limitin biraz altına ayarlayın, örneğin 0.9 * rps_limit: ağ gecikmesi düzensizdir, bu yüzden yarım saniye arayla gönderilen istekler sunucuya birbirine daha yakın ulaşabilir.
İzleme: X-RateLimit-* ve X-Quota-* başlıkları
Veri yanıtı limitlerinizin durumunu taşır: X-RateLimit-Remaining ve X-RateLimit-Reset saniyelik pencerede ne kaldığını ve ne zaman sıfırlanacağını, X-Quota-Remaining, X-Quota-Limit ve X-Quota-Reset ise kalan kotayı, boyutunu ve sıfırlanma unix zamanını verir. Tek bir kalan değerden daha yararlı olan hızdır: dönemin bu noktasında kotanın ne kadarı gitmiş.
PERIOD = 30 * 86400 # Genesis API counts quota per 30 days
def watch(h):
"""Checks limit headroom from the response headers."""
if h.get("X-RateLimit-Remaining") == "0": # window used up
reset = float(h.get("X-RateLimit-Reset", 0))
time.sleep(max(0.0, reset - time.time()))
try:
left = int(h["X-Quota-Remaining"])
limit = int(h["X-Quota-Limit"])
reset = int(h["X-Quota-Reset"])
except (KeyError, ValueError):
return # 429 responses carry no X-Quota-* headers
used = 1 - left / limit
passed = 1 - (reset - time.time()) / PERIOD
if used > passed + 0.05:
print(f"quota is running ahead: {used:.0%} used"
f" with {passed:.0%} of the period gone")
Fonksiyon, limiti dolunca pencerenin sıfırlanmasını bekler ve kota kullanımı takvimin 5 yüzde puandan fazla önüne geçtiğinde uyarır. Örnek (açıklayıcı): 15. güne kadar kotanın %70'i gitmiştir, yani aynı hızla çağrılar dönemin 15 / 0,7 ≈ 21,4. gününde biter. /account/usage aynı sayıları başlıksız verir: calls_used, calls_limit ve period_resets_at.
Birkaç endpoint için zamanlama
Birden çok endpoint olduğunda her birine kendi aralığı verilir ve ilk istekler toplu çıkmasın diye dağıtılır. Aralığı göreve göre seçin, ama asla freshness_sec altına inmeyin: spread'ler planınızın tam hızını ister, birçok strateji için ise fonlama ve açık pozisyon için bir dakika yeterlidir.
import heapq
usage, _ = fetch("/account/usage") # does not use a call
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])
JOBS = { # path -> polling interval, s
"/arbitrage/spot-spot": fresh,
"/funding/spread": max(fresh, 60),
"/market/open-interest": max(fresh, 60),
}
t0 = time.monotonic()
queue = [(t0 + i * fresh / len(JOBS), path, every)
for i, (path, every) in enumerate(JOBS.items())]
heapq.heapify(queue)
while True:
due, path, every = heapq.heappop(queue)
time.sleep(max(0.0, due - time.monotonic()))
bucket.take()
data, hdrs = fetch(path)
watch(hdrs)
print(path, len(data))
heapq.heappush(queue, (due + every, path, every))
Start'ta bu, 30 günde 86.400 + 43.200 + 43.200 = 172.800 çağrı eder, kotanın %8,64'ü: spread'ler 30 saniyede bir, fonlama ve açık pozisyon 60 saniyede bir. İlk istekler 30 / 3 = 10 saniye arayla çıkar, sonra her endpoint kendi ritmini korur ve bucket.take() çakışmalara karşı korur. Bu sorguya dayanan, Telegram bildirimli bir bot Python ile kripto arbitraj botu yazısındadır.
503 ve sunucu hatalarında ne yapmalı
RFC 9110 uyarınca 503 Service Unavailable, geçici aşırı yük veya bakım anlamına gelir ve sunucu Retry-After ile bir bekleme önerebilir. Genesis API'de bu 503 snapshot_not_ready olur: veri yeniden oluşturuluyor veya kaynağı yeniden başlıyordur. Retry-After saniye sonra yeniden deneyin; bekleme genellikle birkaç saniyedir.
Taze yanıt gelmediği sürece botunuz son sorgudan kalan veriyi tutar ve bu veri eskir. Sinyal göndermeden önce meta.updated_at değerini şu anki zamanla karşılaştırın: bir dakikalık anlık görüntüdeki bir çift borsada çoktan kaybolmuş olabilir. Diğer riskler Otomasyon riskleri dersinde anlatılır.
500 internal_error, zaman aşımı ve kopan bağlantıları üstel geri çekilmeyle yeniden deneyin. Hata sürerse X-Request-Id değeri, UTC cinsinden istek zamanı, endpoint ve durum koduyla destek ekibine yazın. Anahtarınızı asla göndermeyin.
Sorular ve cevaplar
Genesis API'ye saniyede kaç istek gönderebilirim?
Planınızın izin verdiği kadar: Trial'da 1, Start'ta 2, Pro'da 5 ve Max'te 15. Limit anahtar başınadır ve 304 yanıtlarını ile hataları içerir. Planınızın değeri X-RateLimit-Limit başlığında ve /account/usage içindeki rps_limit alanındadır.
Hatalar ve 304 yanıtları kotamdan düşer mi?
Hayır. Yalnızca 200 yanıtı kota harcar; 304, 429, 503 ve diğer hatalar ücretsizdir ve hiçbir maliyeti yoktur. Ancak saniyedeki istek limitinde yer kaplarlar, bu yüzden beklemeden yapılan yeniden denemeler yeni 429 yanıtları doğurur.
10 saniyede 60 MB sınırının altında nasıl kalırım?
Gzip'i açın: limit sıkıştırılmış veriyi sayar. Tam veri setlerinde If-None-Match gönderin: 304'ün gövdesi yoktur. Fonlama analitiği gibi ağır bölümleri coin dilimi olarak alın ve aynı tam veri setini freshness_sec'ten sık indirmeyin. 64 KB'ın altındaki yanıtlar sayılmaz ve dokümantasyona göre her veri setini planınızın tazelik aralığında sorgulamak limitin altına rahatça sığar.
429 Too Many Requests hatası ne anlama gelir?
Sunucu, istemci bir zaman penceresinde limiti aştığı için isteği reddetmiştir. Yanıt, beklenecek saniye sayısı olan Retry-After taşıyabilir; yoksa her başarısızlıktan sonra beklemeyi ikiye katlayın. Genesis API'de 429, rate_limited veya download_limited koduyla gelir.