Genesis API रिस्पॉन्स और एरर: JSON फ़ॉर्मेट, ETag और 304, HTTP कोड
संक्षेप में
- Genesis API का सफल रिस्पॉन्स
success,dataऔरmetaका एनवेलप होता है; एरर यानीsuccess: falseऔर कोड व संदेश वालाerrorऑब्जेक्ट। - पिछला ETag
If-None-Matchमें भेजने पर डेटा न बदला हो तो304बिना बॉडी के मिलता है, और 304 कोटा नहीं खाता। 429और503कोRetry-Afterके विराम के बाद दोबारा भेजें।400,401,403,404और410दोबारा भेजने से ठीक नहीं होते — रिक्वेस्ट, कुंजी या प्लान बदलें।
Genesis API हर रिक्वेस्ट का जवाब JSON में देती है, जो key–value ऑब्जेक्ट और ऐरे से बना टेक्स्ट डेटा फ़ॉर्मेट है। सफल रिस्पॉन्स हमेशा success, data और meta के एक ही एनवेलप में आता है; एरर HTTP स्टेटस कोड और error ऑब्जेक्ट के साथ आता है। स्टेटस कोड आपके प्रोग्राम को बताता है कि आगे क्या करना है: डेटा इस्तेमाल करना, Retry-After सेकंड रुककर दोबारा भेजना, या रिक्वेस्ट सुधारना।
रिस्पॉन्स एनवेलप: success, data और meta
दस्तावेज़ से GET /arbitrage/spot-spot का छोटा किया हुआ रिस्पॉन्स (यह एंडपॉइंट हर प्लान में उपलब्ध है):
{
"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"
}
}
| फ़ील्ड | टाइप | विवरण |
|---|---|---|
success | boolean | true — रिक्वेस्ट सफल रही, false — एरर |
data | ऐरे या ऑब्जेक्ट | एंडपॉइंट का डेटा |
meta.count | int | data में आइटम की संख्या |
meta.updated_at | int | डेटा बनने का Unix समय |
meta.freshness_sec | int | आपके प्लान के लिए डेटा देने में देरी, सेकंड में |
meta.plan | string | आपका प्लान, उदाहरण में pro |
अपवाद फंडिंग एनालिटिक्स है: उसके meta में count, updated_at और schema_version होते हैं, freshness_sec और plan नहीं। एनवेलप का वर्णन दस्तावेज़ के रिस्पॉन्स फ़ॉर्मेट सेक्शन में है, और data के फ़ील्ड हर एंडपॉइंट के पेज पर।
सभी एंडपॉइंट पर तीन नियम लागू हैं:
- खाली मान
nullहोता है: जैसे DEX – Futures मेंmax_position_usd, जब एक्सचेंज पोज़िशन की सीमा नहीं देता; - स्प्रेड और दरें प्रतिशत में हैं:
"spread_pct": 0.92का मतलब 0.92% है, 92% नहीं; - टाइमस्टैम्प Unix सेकंड में हैं:
1783802410यानी 11 जुलाई 2026, 20:40:10 UTC; स्ट्रिंग के रूप में भेजी गई तारीखें, जैसे Cross-chain मेंpool_created_at, दस्तावेज़ में स्ट्रिंग टाइप की हैं।
data: पंक्तियों का ऐरे या ऑब्जेक्ट
data का आकार हर एंडपॉइंट के विवरण में लिखा है। GET /arbitrage/spot-spot के लिए यह ऐरे है: हर आर्बिट्राज जोड़ी का एक आइटम, साइट की टेबल की एक पंक्ति जैसा। GET /account/usage के लिए यह एक ही ऑब्जेक्ट है, जिसमें आपकी कुंजी की स्थिति है:
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 हर प्लान में उपलब्ध है और आपका प्लान, कोटा खपत और freshness_sec दिखाता है: इससे ज़्यादा बार पूछने का कोई फ़ायदा नहीं। फ़ील्ड का वर्णन उपयोग में है, और पहली रिक्वेस्ट क्विकस्टार्ट में कदम-दर-कदम समझाई गई है। कई एंडपॉइंट के साथ काम करने वाले कोड को आकार साफ़ तौर पर जाँचना चाहिए: Python में isinstance(data, list)।
फ़िल्टर: वैकल्पिक, बिना फ़िल्टर पूरा डेटासेट
सभी फ़िल्टर पैरामीटर वैकल्पिक हैं: उनके बिना रिक्वेस्ट एंडपॉइंट का पूरा डेटासेट लौटाती है। exchange में कई एक्सचेंज कॉमा से अलग करके लिखें, और coin में कॉइन का टिकर दें:
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 फ़्लैग -d पैरामीटर को क्वेरी स्ट्रिंग में बदल देता है: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5। एक्सचेंज के नाम वैसे ही लिखें जैसे रिस्पॉन्स के फ़ील्ड में लौटते हैं: ByBit, Gate, MEXC। आर्बिट्राज एंडपॉइंट के पैरामीटर आर्बिट्राज एंडपॉइंट गाइड में हैं।
कोटा रिस्पॉन्स गिनता है, पंक्तियाँ नहीं: फ़िल्टर के साथ या बिना, रिक्वेस्ट एक ही कॉल है। फ़िल्टर रिस्पॉन्स की बॉडी घटाता है, और उसके साथ ट्रैफ़िक और डाउनलोड लिमिट की खपत भी। सभी लिमिट Genesis API लिमिट गाइड में हैं।
gzip कम्प्रेशन
क्लाइंट Accept-Encoding: gzip हेडर भेजे तो Genesis API पूरे डेटासेट और बड़े रिस्पॉन्स gzip-कम्प्रेस करके भेजती है (RFC 9110, सेक्शन 12.5.3)। छोटा रिस्पॉन्स बिना कम्प्रेशन के भी आ सकता है।
Python requests यह हेडर खुद भेजता है और रिस्पॉन्स खोल देता है। curl --compressed फ़्लैग के बिना कम्प्रेशन नहीं माँगता; फ़्लैग के साथ वह माँगता भी है और खोलता भी है।
डाउनलोड लिमिट कम्प्रेस्ड डेटा गिनती है: प्रति कुंजी हर 10 सेकंड में अधिकतम 60 MB, और 64 KB से छोटे रिस्पॉन्स नहीं गिने जाते। लिमिट पार होने पर 429 download_limited मिलता है।
ETag और 304: न बदला डेटा छोड़ें
ETag एक रिस्पॉन्स हेडर है जिसमें डेटा के वर्शन का टैग होता है। क्लाइंट यह टैग If-None-Match हेडर में वापस भेजता है। डेटा न बदला हो तो सर्वर बिना बॉडी के 304 Not Modified देता है; बदला हो तो सामान्य 200 नए डेटा और नए ETag के साथ।
# पूरा डेटासेट, बिना फ़िल्टर: सिर्फ़ रिस्पॉन्स हेडर प्रिंट करें
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# पहले रिस्पॉन्स के ETag के साथ दोहराएँ (उदाहरण का मान)
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 बिना फ़िल्टर वाली रिक्वेस्ट के रिस्पॉन्स के साथ आता है और हर नए डेटा स्नैपशॉट के साथ बदलता है। फ़िल्टर वाली रिक्वेस्ट का रिस्पॉन्स उसी रिक्वेस्ट के लिए बनता है और बिना ETag के आता है; वहाँ फ़िल्टर खुद ट्रैफ़िक बचाता है। ETag धीमे बदलने वाले डेटा पर सबसे ज़्यादा काम आता है: फंडिंग एनालिटिक्स के सारांश का ETag लगभग हर 15 मिनट में बदलता है, और 304 जवाब उसकी पूरे-डाउनलोड वाली लिमिट में नहीं गिने जाते।
304 रिस्पॉन्स कोटा नहीं खाता, पर प्रति-सेकंड रिक्वेस्ट लिमिट में गिना जाता है। टैग को ठीक वैसा ही वापस भेजें जैसा आया था: RFC 9110 के अनुसार यह उद्धरण चिह्नों वाली स्ट्रिंग है, और W/ उपसर्ग कमज़ोर टैग का संकेत है।
एरर कोड और क्या करें
एरर पर Genesis API संबंधित HTTP स्टेटस और success: false वाली बॉडी लौटाती है:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code मशीन-पठनीय कोड है, जिस पर आपका प्रोग्राम शाखा बना सकता है। error.message इंसान के लिए स्पष्टीकरण है: 400 पर कारण बताता है, 410 पर बदले हुए एंडपॉइंट का पता।
| HTTP | error.code | मतलब | क्या करें |
|---|---|---|---|
400 | bad_request | रिक्वेस्ट के पैरामीटर गलत हैं, जैसे /orderbooks/exec पर volume=700 | message के अनुसार पैरामीटर सुधारें: वही रिक्वेस्ट फिर विफल होगी |
401 | invalid_key | कुंजी अनुपस्थित, अमान्य या रद्द है, या API सब्सक्रिप्शन समाप्त हो गया | X-API-Key हेडर और प्रोफ़ाइल में सब्सक्रिप्शन की स्थिति जाँचें |
403 | plan_restricted | एंडपॉइंट आपके प्लान में नहीं है | जिस प्लान में वह है उस पर जाएँ या रिक्वेस्ट छोड़ दें |
404 | not_found | एंडपॉइंट या संसाधन नहीं मिला: डेटासेट, सेक्शन, कॉइन, ऑर्डर बुक | पाथ और पैरामीटर दस्तावेज़ से मिलाएँ |
410 | gone | एंडपॉइंट बंद कर दिया गया है | message में दिए पते पर जाएँ |
429 | rate_limited | प्रति-सेकंड रिक्वेस्ट लिमिट पार हो गई, या अवधि का कोटा खत्म हो गया | Retry-After सेकंड रुकें और गति घटाएँ; कोटा खत्म हो तो रीसेट की प्रतीक्षा करें या प्लान बढ़ाएँ |
429 | download_limited | डाउनलोड की मात्रा पार हुई: प्रति कुंजी हर 10 सेकंड में 60 MB कम्प्रेस्ड डेटा | Retry-After तक रुकें, फ़िल्टर, coin और If-None-Match से ट्रैफ़िक घटाएँ |
500 | internal_error | आंतरिक त्रुटि | बाद में दोबारा भेजें; बनी रहे तो X-Request-Id के साथ सहायता से संपर्क करें |
503 | snapshot_not_ready | डेटा दोबारा बन रहा है या उसका स्रोत रीस्टार्ट हो रहा है | Retry-After सेकंड बाद दोबारा भेजें |
Retry-After हेडर 429 और 503 के साथ आता है और प्रतीक्षा के सेकंड बताता है: आमतौर पर कुछ सेकंड, लेकिन अवधि का कोटा खत्म होने पर यह कोटा रीसेट होने तक का समय है, जो कई दिन हो सकता है। 4xx और 5xx एरर कोटा नहीं खाते, पर प्रति-सेकंड रिक्वेस्ट लिमिट में गिने जाते हैं, इसलिए जल्दी दोबारा भेजने पर अक्सर वही एरर लौटता है। शब्दकोश के शब्द: HTTP 429 और rate limit।
X-Request-Id: सहायता को क्या भेजें
Genesis API का हर रिस्पॉन्स, सफल हो या नहीं, X-Request-Id हेडर में रिक्वेस्ट की पहचान लेकर आता है। कोई एरर बार-बार आए या डेटा गलत लगे तो सहायता को भेजें:
X-Request-Idका मान;- UTC में रिक्वेस्ट का समय;
- पैरामीटर के साथ एंडपॉइंट, जैसे
GET /arbitrage/spot-spot?coin=BTC; - HTTP स्टेटस और
error.code।
अपनी कुंजी न भेजें। अगर वह किसी चैट, लॉग या ऐसे कोड में पहुँच गई जिसे दूसरे देख सकते हैं, तो प्रोफ़ाइल में उसे दोबारा जारी करें: पुरानी कुंजी तुरंत काम करना बंद कर देती है।
रिस्पॉन्स संभालने का क्रम
स्टेटस कोड जाँचें
200—dataऔरmetaपढ़ें, और ETag आया हो तो सहेजें।304— पिछले रिस्पॉन्स का डेटा इस्तेमाल करें।अस्थायी एरर संभालें
छोटे विराम वाले
429और503—Retry-Afterसेकंड रुकें और दोबारा भेजें, लगातार अधिकतम तीन बार।500— बाद में दोबारा भेजें।रिक्वेस्ट की गलतियों पर रुकें
400,401,403,404,410, और घंटों या दिनों के विराम वाला429— पैरामीटर, कुंजी या प्लान सुधारें, या कोटा रीसेट की प्रतीक्षा करें।डेटा की उम्र जाँचें
meta.updated_atकी तुलना मौजूदा समय से करें: पुराने स्नैपशॉट पर काम करने वाला बॉट ऐसे स्प्रेड देखता है जो अब हैं ही नहीं।अगली रिक्वेस्ट तय करें
meta.freshness_secसेकंड से पहले नहीं, और बिना फ़िल्टर वाली रिक्वेस्ट मेंIf-None-Matchके साथ।
Python में get_json फ़ंक्शन
यह फ़ंक्शन ये नियम एक साथ जोड़ता है: हर पते का आख़िरी ETag रखता है और 304 पर पिछला डेटा लौटाता है, 429 और 503 पर Retry-After रुकता है और तीन बार तक दोबारा भेजता है, पर एक मिनट से लंबे विराम का इंतज़ार नहीं करता। बाकी एरर पर स्टेटस, संदेश और X-Request-Id के साथ exception उठता है। कुंजी GENESIS_API_KEY एनवायरनमेंट वेरिएबल से आती है।
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 = {} # (पाथ, पैरामीटर) -> (ETag, डेटा)
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): # एक रिक्वेस्ट और अधिकतम 3 रीट्राई
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] # डेटा नहीं बदला
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # घंटों या दिनों का इंतज़ार नहीं करते
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "not JSON") 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: # सिर्फ़ बिना फ़िल्टर वाले रिस्पॉन्स पर
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
timeout=15 पैरामीटर ज़रूरी है: टाइमआउट के बिना requests रिस्पॉन्स के लिए हमेशा इंतज़ार करता रहता है।
अपने प्लान के अंतराल पर पोलिंग: पूरा डेटासेट ETag के साथ आता है, और पंक्तियाँ कोड में फ़िल्टर होती हैं। 4xx एरर प्रोग्राम रोक देते हैं; सर्वर की विफलता अगले चक्र तक रुकती है।
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # पूरा डेटासेट
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "जोड़ियाँ 1% या उससे अधिक स्प्रेड के साथ")
except GenesisError as e:
if e.status < 500:
raise # 4xx: रिक्वेस्ट, कुंजी, प्लान या कोटा
print("सर्वर एरर, अगले चक्र में दोबारा कोशिश:", e)
time.sleep(pause)
सवाल और जवाब
क्या 304 रिस्पॉन्स कोटा खाता है?
नहीं। सिर्फ़ 200 रिस्पॉन्स कोटा खाते हैं। 304 रिस्पॉन्स और 4xx व 5xx एरर मुफ़्त हैं, पर प्रति-सेकंड रिक्वेस्ट लिमिट में गिने जाते हैं।
410 के बाद क्या करूँ?
एंडपॉइंट बंद हो चुका है और बदला हुआ पता error.message में है। उदाहरण के लिए GET /arbitrage/predictions 15 नवंबर 2026 को बंद हुआ, और उसका message /predictions/arbitrage की ओर इशारा करता है। अपने कोड में पाथ बदल लें।
एरर नहीं है फिर भी data खाली क्यों है?
फ़िल्टर ने सारी पंक्तियाँ हटा दीं: जैसे min_spread सभी मौजूदा स्प्रेड से ऊपर है। ऐसे रिस्पॉन्स में meta.count 0 होता है, इसलिए फ़िल्टर ढीला करें।
रिस्पॉन्स में ETag क्यों नहीं है?
ETag बिना फ़िल्टर वाली रिक्वेस्ट के रिस्पॉन्स के साथ आता है। coin, exchange, min_spread या किसी और फ़िल्टर वाली रिक्वेस्ट का रिस्पॉन्स उसी रिक्वेस्ट के लिए बनता है और बिना टैग के आता है, इसलिए उस पर If-None-Match लागू नहीं होता।