Genesis API yanıtları ve hataları: JSON biçimi, ETag ve 304, HTTP kodları
Kısaca
- Başarılı bir Genesis API yanıtı
success,datavemetazarfıdır; hata isesuccess: falseile kod ve mesaj içeren birerrornesnesidir. - Önceki ETag'i
If-None-Matchile göndermek, veri değişmemişse gövdesiz304döndürür ve 304 kota harcamaz. 429ve503yanıtlarınıRetry-Aftersüresi kadar bekleyip yeniden deneyin.400,401,403,404ve410yeniden denemeyle düzelmez — isteği, anahtarı veya tarifeyi değiştirin.
Genesis API her isteğe JSON ile yanıt verir; JSON, anahtar–değer nesnelerinden ve dizilerden oluşan bir metin veri biçimidir. Başarılı yanıt her zaman success, data ve meta içeren aynı zarfta gelir; hata ise bir HTTP durum kodu ve bir error nesnesiyle gelir. Durum kodu programınıza ne yapacağını söyler: veriyi kullanmak, Retry-After saniye bekleyip yeniden denemek veya isteği düzeltmek.
Yanıt zarfı: success, data ve meta
Dokümantasyondan kısaltılmış bir GET /arbitrage/spot-spot yanıtı (uç nokta her tarifede kullanılabilir):
{
"success": true,
"data": [
{
"coin": "FUEL",
"exchange_buy": "ByBit",
"exchange_sell": "Gate",
"spread_pct": 0.11,
…
}
],
"meta": {
"count": 214,
"updated_at": 1783802410,
"freshness_sec": 10,
"plan": "pro"
}
}
| Alan | Tür | İçerik |
|---|---|---|
success | boolean | true — istek başarılı, false — hata |
data | dizi veya nesne | Uç noktanın verisi |
meta.count | int | data içindeki öğe sayısı |
meta.updated_at | int | Verinin oluşturulduğu Unix zamanı |
meta.freshness_sec | int | Tarifeniz için sunum gecikmesi, saniye |
meta.plan | string | Tarifeniz, örnekte pro |
İstisna fonlama analitiğidir: meta alanında count, updated_at ve schema_version bulunur, freshness_sec ve plan yoktur. Zarf, dokümantasyonun Yanıt formatı bölümünde, data alanları ise her uç noktanın sayfasında anlatılır.
Üç kural her uç nokta için geçerlidir:
- boş değer
nullolur: örneğin DEX – Futures'takimax_position_usd, borsa pozisyon limiti vermiyorsanull'dır; - spreadler ve oranlar yüzde cinsindendir:
"spread_pct": 0.92değeri yüzde 0,92 demektir, yüzde 92 değil; - zaman damgaları Unix saniyesidir:
1783802410, 11 Temmuz 2026, 20:40:10 UTC'dir; Cross-chain'dekipool_created_atgibi dize olarak gönderilen tarihler dokümantasyonda string türündedir.
data: satır dizisi veya nesne
data biçimi her uç noktanın açıklamasında belirtilir. GET /arbitrage/spot-spot için bu bir dizidir: her arbitraj çifti için bir öğe, sitedeki tablonun bir satırı gibi. GET /account/usage için ise anahtarınızın durumunu içeren tek bir nesnedir:
curl "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"success": true,
"data": {
"plan": "pro",
"calls_used": 184201,
"calls_limit": 5000000,
"rps_limit": 5,
"freshness_sec": 10,
"period_resets_at": 1786492800
},
"meta": { … }
}
/account/usage her tarifede kullanılabilir; tarifenizi, kota kullanımınızı ve freshness_sec değerini gösterir: bundan sık sorgulamanın faydası yoktur. Alanlar Kullanım bölümünde, ilk istek ise hızlı başlangıç rehberinde adım adım anlatılır. Birkaç uç noktayla çalışan kod, biçimi açıkça kontrol etmelidir: Python'da isinstance(data, list).
Filtreler: isteğe bağlı, filtresiz tam veri seti
Tüm filtre parametreleri isteğe bağlıdır: onlarsız yapılan istek, uç noktanın tam veri setini döndürür. exchange alanına birkaç borsayı virgülle ayırarak yazın, coin alanına coini tickerıyla verin:
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
-G bayrağı -d parametrelerini sorgu dizesine çevirir: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Borsa adlarını yanıt alanlarında döndüğü şekilde yazın: ByBit, Gate, MEXC. Arbitraj uç noktalarının parametreleri arbitraj uç noktaları rehberinde yer alır.
Kota satırları değil yanıtları sayar: filtreli veya filtresiz bir istek tek çağrıdır. Filtre yanıt gövdesini, dolayısıyla trafiği ve indirme limiti kullanımını azaltır. Tüm limitler Genesis API limitleri rehberinde ele alınır.
gzip sıkıştırma
Genesis API, istemci Accept-Encoding: gzip başlığını gönderdiğinde tam veri setlerini ve büyük yanıtları gzip ile sıkıştırarak gönderir (RFC 9110, bölüm 12.5.3). Küçük bir yanıt sıkıştırılmadan gelebilir.
Python requests bu başlığı kendisi gönderir ve yanıtı açar. curl, --compressed bayrağı olmadan sıkıştırma istemez; bayrakla birlikte hem ister hem açar.
İndirme limiti sıkıştırılmış veriyi sayar: anahtar başına 10 saniyede en fazla 60 MB; 64 KB'tan küçük yanıtlar sayılmaz. Limit aşılırsa 429 download_limited alırsınız.
ETag ve 304: değişmeyen veriyi atlayın
ETag, verinin sürüm etiketini taşıyan bir yanıt başlığıdır. İstemci bu etiketi If-None-Match başlığında geri gönderir. Veri değişmemişse sunucu gövdesiz 304 Not Modified döndürür; değişmişse yeni veri ve yeni ETag ile normal bir 200 verir.
# Tam veri seti, filtresiz: yalnızca yanıt başlıklarını yazdır
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# İlk yanıttaki ETag ile tekrarla (örnek değer)
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
-H 'If-None-Match: W/"5d1f0c9a"'
ETag, filtresiz isteğin yanıtıyla gelir ve her yeni veri anlık görüntüsüyle değişir. Filtreli isteğin yanıtı o istek için oluşturulur ve ETag olmadan gelir; orada trafiği filtrenin kendisi azaltır. ETag en çok yavaş değişen verilerde işe yarar: fonlama analitiği özetinin ETag'i yaklaşık 15 dakikada bir değişir ve 304 yanıtları onun tam indirme limitine sayılmaz.
304 yanıtı kota harcamaz, ancak saniyedeki istek limitine sayılır. Etiketi geldiği gibi geri gönderin: RFC 9110 uyarınca etiket tırnak içinde bir dizedir ve W/ öneki zayıf etiketi belirtir.
Hata kodları ve ne yapmalı
Hata durumunda Genesis API ilgili HTTP durum kodunu ve success: false içeren bir gövde döndürür:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code, programınızın dallanabileceği makine tarafından okunabilir bir koddur. error.message insan için açıklamadır: 400 için nedeni, 410 için yeni adresi verir.
| HTTP | error.code | Anlamı | Ne yapmalı |
|---|---|---|---|
400 | bad_request | Geçersiz istek parametreleri, örneğin /orderbooks/exec üzerinde volume=700 | Parametreleri message'a göre düzeltin: aynı istek yine başarısız olur |
401 | invalid_key | Anahtar yok, geçersiz veya iptal edilmiş ya da API aboneliği sona ermiş | X-API-Key başlığını ve profilinizdeki abonelik durumunu kontrol edin |
403 | plan_restricted | Uç nokta tarifenizde yok | Onu içeren bir tarifeye geçin veya isteği bırakın |
404 | not_found | Uç nokta veya kaynak bulunamadı: veri seti, bölüm, coin, emir defteri | Yolu ve parametreleri dokümantasyonla karşılaştırın |
410 | gone | Uç nokta kaldırıldı | message içinde verilen adrese geçin |
429 | rate_limited | Saniyedeki istek limiti aşıldı veya dönem kotası bitti | Retry-After saniye bekleyin ve yavaşlayın; kota bittiyse sıfırlanmayı bekleyin veya tarifeyi yükseltin |
429 | download_limited | İndirme hacmi aşıldı: anahtar başına 10 sn'de 60 MB sıkıştırılmış veri | Retry-After kadar bekleyin, trafiği filtrelerle, coin ve If-None-Match ile azaltın |
500 | internal_error | İç hata | Daha sonra yeniden deneyin; sürerse X-Request-Id ile desteğe yazın |
503 | snapshot_not_ready | Veri yeniden oluşturuluyor veya kaynağı yeniden başlıyor | Retry-After saniye sonra yeniden deneyin |
Retry-After başlığı 429 ve 503 ile gelir ve beklenecek saniye sayısını taşır: genellikle birkaç saniyedir, ancak dönem kotası bittiğinde kotanın sıfırlanmasına kalan süredir ve bu günler olabilir. 4xx ve 5xx hataları kota harcamaz ancak saniyedeki istek limitine sayılır; bu yüzden erken yapılan yeniden deneme büyük olasılıkla aynı hatayı döndürür. Sözlük maddeleri: HTTP 429 ve rate limit.
X-Request-Id: desteğe ne gönderilir
Başarılı olsun olmasın her Genesis API yanıtı, isteğin tanımlayıcısını içeren bir X-Request-Id başlığı taşır. Hata tekrar ediyorsa veya veri yanlış görünüyorsa desteğe şunları gönderin:
X-Request-Iddeğeri;- UTC olarak istek zamanı;
- parametreleriyle uç nokta, örneğin
GET /arbitrage/spot-spot?coin=BTC; - HTTP durumu ve
error.code.
Anahtarınızı göndermeyin. Anahtar bir sohbete, günlüklere veya başkalarının görebileceği koda düştüyse profilinizde yeniden oluşturun: eski anahtar hemen çalışmayı bırakır.
Yanıtları işleme sırası
Durum kodunu kontrol edin
200—datavemetaalanlarını okuyun, ETag geldiyse saklayın.304— önceki yanıttaki veriyi kullanın.Geçici hataları işleyin
Kısa beklemeli
429ve503—Retry-Aftersaniye bekleyip yeniden deneyin, üst üste en fazla üç kez.500— daha sonra yeniden deneyin.İstek hatalarında durun
400,401,403,404,410ve saatler veya günler süren beklemeli429— parametreleri, anahtarı veya tarifeyi düzeltin ya da kota sıfırlanmasını bekleyin.Verinin yaşını kontrol edin
meta.updated_atdeğerini şimdiki zamanla karşılaştırın: eski anlık görüntüyle işlem yapan bir bot, çoktan kaybolmuş spreadler görür.Sonraki isteği planlayın
En erken
meta.freshness_secsaniye sonra, filtresiz isteklerdeIf-None-Matchile.
Python'da get_json fonksiyonu
Fonksiyon bu kuralları bir araya getirir: her adres için son ETag'i saklar ve 304 durumunda önceki veriyi döndürür, 429 ve 503 durumunda Retry-After kadar bekleyip üç kereye kadar yeniden dener, ancak bir dakikadan uzun beklemeleri beklemez. Diğer hatalar durum kodu, mesaj ve X-Request-Id ile bir istisna oluşturur. Anahtar GENESIS_API_KEY ortam değişkeninden gelir.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # (path, params) -> (ETag, data)
class GenesisError(Exception):
def __init__(self, status, text):
super().__init__(f"{status} {text}")
self.status = status
def get_json(path, params=None):
key = (path, tuple(sorted((params or {}).items())))
for attempt in range(4): # bir istek ve en fazla 3 yeniden deneme
hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
r = session.get(BASE + path, params=params,
headers=hdr, timeout=15)
if r.status_code == 304:
return cache[key][1] # veri değişmedi
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # saatler veya günler asla beklenmez
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "JSON değil") from None
if r.status_code != 200 or not body.get("success"):
err = body.get("error") or {}
raise GenesisError(r.status_code, (
f"{err.get('code')}: {err.get('message')}; "
f"X-Request-Id {r.headers.get('X-Request-Id')}"))
if "ETag" in r.headers: # yalnızca filtresiz yanıtlarda
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
timeout=15 parametresi şarttır: zaman aşımı olmadan requests yanıtı sonsuza kadar bekler.
Tarifenizin aralığında sorgulama: tam veri seti ETag ile gelir, satırlar kodda süzülür. 4xx hataları programı durdurur; sunucu arızası bir sonraki döngüyü bekler.
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # tam veri seti
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "çiftte spread %1 veya üzeri")
except GenesisError as e:
if e.status < 500:
raise # 4xx: istek, anahtar, tarife veya kota
print("sunucu hatası, sonraki döngüde yeniden denenecek:", e)
time.sleep(pause)
Sorular ve cevaplar
304 yanıtı kota harcar mı?
Hayır. Yalnızca 200 yanıtları kota harcar. 304 yanıtları ile 4xx ve 5xx hataları ücretsizdir, ancak saniyedeki istek limitine sayılır.
410 sonrasında ne yapmalıyım?
Uç nokta kaldırılmıştır ve yeni adres error.message içindedir. Örneğin GET /arbitrage/predictions 15 Kasım 2026'da kaldırıldı ve message alanı /predictions/arbitrage adresini gösterir. Koddaki yolu güncelleyin.
Hata yokken data neden boş?
Filtreler tüm satırları eledi: örneğin min_spread, mevcut tüm spreadlerden yüksek. Böyle bir yanıtta meta.count 0'dır; filtreyi gevşetin.
Yanıtta neden ETag yok?
ETag, filtresiz isteğin yanıtıyla gelir. coin, exchange, min_spread veya başka bir filtreyle yapılan isteğin yanıtı o istek için oluşturulur ve etiketsiz gelir, bu yüzden If-None-Match ona uygulanmaz.