Réponses et erreurs de Genesis API : format JSON, ETag et 304, codes HTTP
En bref
- Une réponse réussie de Genesis API est une enveloppe
success,dataetmeta; une erreur estsuccess: falseplus un objeterroravec un code et un message. - Si vous renvoyez l’ETag précédent dans
If-None-Match, le serveur répond304sans corps quand les données n’ont pas changé, et un 304 ne consomme pas de quota. - Réessayez
429et503après la pauseRetry-After. Réessayer ne corrige pas400,401,403,404ni410: changez la requête, la clé ou le plan.
Genesis API répond à chaque requête en JSON, un format de données texte fait d’objets clé–valeur et de tableaux. Une réponse réussie arrive toujours dans la même enveloppe success, data et meta ; une erreur arrive avec un code de statut HTTP et un objet error. Le code de statut indique à votre programme quoi faire : utiliser les données, attendre Retry-After secondes puis réessayer, ou corriger la requête.
Enveloppe de la réponse : success, data et meta
Une réponse abrégée de GET /arbitrage/spot-spot, tirée de la documentation (le endpoint est disponible sur tous les plans) :
{
"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"
}
}
| Champ | Type | Contenu |
|---|---|---|
success | boolean | true : la requête a abouti, false : erreur |
data | tableau ou objet | Les données du endpoint |
meta.count | int | Nombre d’éléments dans data |
meta.updated_at | int | Heure unix de construction des données |
meta.freshness_sec | int | Délai de diffusion pour votre plan, en secondes |
meta.plan | string | Votre plan, pro dans l’exemple |
L’exception est l’analytique du funding : son meta contient count, updated_at et schema_version, sans freshness_sec ni plan. L’enveloppe est décrite dans la section Format de réponse de la documentation, et les champs de data sur la page de chaque endpoint.
Trois conventions valent pour tous les endpoints :
- une valeur vide est
null: par exemple,max_position_usddans DEX – Futures vautnullquand la plateforme ne fournit pas de limite de position ; - les spreads et les taux sont des pourcentages :
"spread_pct": 0.92signifie 0,92 %, pas 92 % ; - les horodatages sont en secondes unix :
1783802410correspond au 11 juillet 2026, 20:40:10 UTC ; les dates envoyées sous forme de chaîne, commepool_created_atdans Cross-chain, ont le type string dans la documentation.
data : un tableau de lignes ou un objet
La forme de data est indiquée dans la description de chaque endpoint. Pour GET /arbitrage/spot-spot, c’est un tableau : un élément par paire d’arbitrage, comme une ligne du tableau du site. Pour GET /account/usage, c’est un seul objet avec l’état de votre clé :
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 est disponible sur tous les plans et affiche votre plan, la consommation du quota et freshness_sec : interroger plus souvent n’apporte rien. Les champs sont décrits dans Utilisation, et la première requête est détaillée pas à pas dans le démarrage rapide. Un code qui manipule plusieurs endpoints doit vérifier la forme explicitement : isinstance(data, list) en Python.
Filtres : facultatifs, jeu de données complet sans eux
Tous les paramètres de filtre sont facultatifs : une requête sans filtre renvoie le jeu de données complet du endpoint. Indiquez plusieurs plateformes dans exchange, séparées par des virgules, et une crypto par son ticker dans 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"
L’option -G transforme les paramètres -d en chaîne de requête : ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Écrivez les noms des plateformes comme ils reviennent dans les champs de la réponse : ByBit, Gate, MEXC. Les paramètres des endpoints d’arbitrage sont dans le guide des endpoints d’arbitrage.
Le quota compte les réponses, pas les lignes : une requête avec ou sans filtre est un appel. Un filtre réduit le corps de la réponse, donc le trafic et la consommation de la limite de téléchargement. Toutes les limites sont détaillées dans le guide des limites de Genesis API.
Compression gzip
Genesis API envoie les jeux de données complets et les réponses volumineuses compressés en gzip lorsque le client envoie l’en-tête Accept-Encoding: gzip (RFC 9110, section 12.5.3). Une petite réponse peut arriver non compressée.
requests de Python envoie cet en-tête lui-même et décompresse la réponse. curl ne demande pas la compression sans l’option --compressed ; avec elle, il la demande et décompresse.
La limite de téléchargement compte les données compressées : au plus 60 Mo par tranche de 10 secondes et par clé, et les réponses de moins de 64 Ko ne sont pas comptées. Au-delà, vous recevez 429 download_limited.
ETag et 304 : ignorer les données inchangées
ETag est un en-tête de réponse qui contient une étiquette de version des données. Le client renvoie cette étiquette dans l’en-tête If-None-Match. Si les données n’ont pas changé, le serveur répond 304 Not Modified sans corps ; sinon, un 200 ordinaire avec de nouvelles données et un nouvel ETag.
# Jeu de données complet, sans filtres : afficher uniquement les en-têtes de la réponse
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# Répéter avec l’ETag de la première réponse (valeur d’illustration)
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"'
Un ETag accompagne la réponse à une requête sans filtres et change à chaque nouvel instantané des données. La réponse à une requête filtrée est construite pour cette requête et arrive sans ETag ; dans ce cas, le filtre lui-même économise le trafic. Les ETag aident surtout pour les données qui évoluent lentement : le résumé de l’analytique du funding change d’ETag environ toutes les 15 minutes, et les réponses 304 ne comptent pas dans sa limite de téléchargement complet.
Une réponse 304 ne consomme pas de quota, mais compte dans la limite de requêtes par seconde. Renvoyez l’étiquette exactement comme elle est arrivée : selon la RFC 9110, c’est une chaîne entre guillemets, et le préfixe W/ indique une étiquette faible.
Codes d’erreur et conduite à tenir
En cas d’erreur, Genesis API renvoie le statut HTTP correspondant et un corps avec success: false :
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code est un code lisible par machine sur lequel votre programme peut brancher sa logique. error.message est l’explication pour un humain : pour 400, elle donne la raison ; pour 410, l’adresse de remplacement.
| HTTP | error.code | Signification | Que faire |
|---|---|---|---|
400 | bad_request | Paramètres de requête invalides, par exemple volume=700 sur /orderbooks/exec | Corrigez les paramètres d’après message : la même requête échouera à nouveau |
401 | invalid_key | Clé absente, invalide ou révoquée, ou abonnement à l’API expiré | Vérifiez l’en-tête X-API-Key et l’état de l’abonnement dans votre profil |
403 | plan_restricted | Le endpoint n’est pas dans votre plan | Passez à un plan qui l’inclut ou supprimez la requête |
404 | not_found | Endpoint ou ressource introuvable : jeu de données, section, crypto, carnet d’ordres | Vérifiez le chemin et les paramètres dans la documentation |
410 | gone | Le endpoint est retiré | Passez à l’adresse indiquée dans message |
429 | rate_limited | Limite de requêtes par seconde dépassée, ou quota de la période épuisé | Attendez Retry-After secondes et ralentissez ; si le quota est épuisé, attendez la réinitialisation ou changez de plan |
429 | download_limited | Volume de téléchargement dépassé : 60 Mo de données compressées par tranche de 10 s et par clé | Attendez Retry-After, réduisez le trafic avec des filtres, coin et If-None-Match |
500 | internal_error | Erreur interne | Réessayez plus tard ; si elle persiste, contactez le support avec le X-Request-Id |
503 | snapshot_not_ready | Les données sont en cours de reconstruction ou leur source redémarre | Réessayez après Retry-After secondes |
L’en-tête Retry-After accompagne 429 et 503 et contient le nombre de secondes à attendre : en général quelques secondes, mais quand le quota de la période est épuisé, c’est le temps avant sa réinitialisation, qui peut se compter en jours. Les erreurs 4xx et 5xx ne consomment pas de quota, mais comptent dans la limite de requêtes par seconde : un nouvel essai trop tôt renverra très probablement la même erreur. Termes du glossaire : HTTP 429 et rate limit.
X-Request-Id : quoi envoyer au support
Chaque réponse de Genesis API, réussie ou non, porte un en-tête X-Request-Id avec l’identifiant de la requête. Si une erreur revient ou si les données semblent fausses, envoyez au support :
- la valeur de
X-Request-Id; - l’heure de la requête en UTC ;
- le endpoint avec ses paramètres, par exemple
GET /arbitrage/spot-spot?coin=BTC; - le statut HTTP et
error.code.
N’envoyez pas votre clé. Si elle s’est retrouvée dans un chat, des journaux ou du code visible par d’autres personnes, réémettez-la dans votre profil : l’ancienne clé cesse de fonctionner immédiatement.
Ordre de traitement d’une réponse
Vérifier le code de statut
200: lisezdataetmeta, et conservez l’ETag s’il est présent.304: utilisez les données de la réponse précédente.Traiter les erreurs temporaires
429et503avec une courte pause : attendezRetry-Aftersecondes et réessayez, trois fois de suite au maximum.500: réessayez plus tard.S’arrêter sur les erreurs de requête
400,401,403,404,410, et un429avec une pause de plusieurs heures ou jours : corrigez les paramètres, la clé ou le plan, ou attendez la réinitialisation du quota.Vérifier l’âge des données
Comparez
meta.updated_atavec l’heure actuelle : un bot qui agit sur un vieil instantané voit des spreads qui ont déjà disparu.Planifier la requête suivante
Pas avant
meta.freshness_secsecondes plus tard, avecIf-None-Matchpour les requêtes sans filtres.
Une fonction get_json en Python
La fonction réunit ces règles : elle garde le dernier ETag de chaque adresse et renvoie les données précédentes sur 304, attend Retry-After sur 429 et 503 et réessaie jusqu’à trois fois, mais n’attend pas les pauses de plus d’une minute. Les autres erreurs lèvent une exception avec le statut, le message et le X-Request-Id. La clé vient de la variable d’environnement 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 = {} # (chemin, paramètres) -> (ETag, données)
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): # une requête plus jusqu’à 3 nouvelles tentatives
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] # les données n’ont pas changé
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # ne jamais attendre des heures ou des jours
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "pas du 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: # seulement sur les réponses sans filtres
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
Le paramètre timeout=15 est indispensable : sans délai d’attente, requests attend une réponse indéfiniment.
Interrogation à l’intervalle de votre plan : le jeu de données complet arrive avec un ETag et les lignes sont filtrées dans le code. Les erreurs 4xx arrêtent le programme ; une panne du serveur attend le cycle suivant.
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # jeu de données complet
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "paires avec un spread de 1 % ou plus")
except GenesisError as e:
if e.status < 500:
raise # 4xx : la requête, la clé, le plan ou le quota
print("erreur serveur, nouvel essai au prochain cycle :", e)
time.sleep(pause)
Questions et réponses
Une réponse 304 consomme-t-elle du quota ?
Non. Seules les réponses 200 consomment du quota. Les réponses 304 et les erreurs 4xx et 5xx sont gratuites, mais comptent dans la limite de requêtes par seconde.
Que faire après un 410 ?
Le endpoint est retiré et l’adresse de remplacement figure dans error.message. Par exemple, GET /arbitrage/predictions a été retiré le 15 novembre 2026 et son message renvoie vers /predictions/arbitrage. Mettez à jour le chemin dans votre code.
Pourquoi data est-il vide sans erreur ?
Les filtres ont éliminé toutes les lignes : par exemple, min_spread est supérieur à tous les spreads actuels. Une telle réponse a meta.count égal à 0 ; assouplissez le filtre.
Pourquoi n’y a-t-il pas d’ETag dans la réponse ?
Un ETag accompagne la réponse à une requête sans filtres. La réponse à une requête avec coin, exchange, min_spread ou un autre filtre est construite pour cette requête et arrive sans étiquette, donc If-None-Match ne s’y applique pas.