Limites de Genesis API : quota d’appels, requêtes par seconde, fraîcheur des données et erreurs 429
En bref
- Votre forfait fixe le quota d’appels sur 30 jours (de 500 000 en Trial à 10 millions en Max), la limite de requêtes par seconde (de 1 à 15) et la fraîcheur des données (de 60 à 5 secondes).
- Seule une réponse
200consomme du quota. Les réponses304et les erreurs sont gratuites, mais occupent un créneau dans la limite de requêtes par seconde ; au-delà d’une limite, le serveur renvoie429et ne facture rien. - Interroger plus vite que
meta.freshness_secn’apporte aucune donnée nouvelle : votre forfait reçoit un nouvel instantané une fois par cet intervalle, etIf-None-Matchtransforme les requêtes en trop en réponses304gratuites.
Les limites de Genesis API sont quatre plafonds par clé : le quota d’appels sur une période de 30 jours, le rate limit en requêtes par seconde, la fraîcheur des données et le volume de téléchargement. Votre forfait fixe les trois premiers ; le volume de téléchargement est le même pour tous : 60 Mo de données compressées toutes les 10 secondes. Au-delà de n’importe quelle limite, le serveur renvoie une erreur 429 et ne facture rien.
Limites par forfait
| Forfait | Appels par 30 jours | Requêtes par seconde | Fraîcheur |
|---|---|---|---|
| Trial, 20 $/mois | 500 000 | 1 | 60 s |
| Start, 50 $/mois | 2 000 000 | 2 | 30 s |
| Pro, 100 $/mois | 5 000 000 | 5 | 10 s |
| Max, 200 $/mois | 10 000 000 | 15 | 5 s |
La fraîcheur des données est l’intervalle auquel votre forfait reçoit un nouvel instantané : toutes les 60 secondes en Trial, toutes les 5 en Max. Les réponses l’indiquent dans le champ meta.freshness_sec. Payer 3 mois fait économiser 10 %, 6 mois 20 %. La comparaison des forfaits se trouve sur la page tarifs de Genesis API, et les règles dans la section Plans et limites de la documentation.
Ce qui consomme le quota
Un appel est une réponse 200. Les réponses 304 (données non modifiées) et les erreurs 4xx et 5xx ne consomment pas de quota, mais comptent dans la limite de requêtes par seconde. Une requête vers /account/usage ne consomme aucun appel.
Le quota couvre une période de 30 jours, pas un mois calendaire. L’heure de réinitialisation figure dans l’en-tête X-Quota-Reset, dans le champ period_resets_at et dans la ligne « resets … » de votre profil. Quand le quota est épuisé, le serveur répond 429 rate_limited, et Retry-After contient le nombre de secondes avant la réinitialisation, ce qui peut représenter des jours.
En-têtes de rate limit
La réponse d’un endpoint de données porte l’état de vos limites (valeurs d’illustration) :
| En-tête | Exemple | Ce qu’il indique |
|---|---|---|
X-RateLimit-Limit | 5 | Limite de requêtes par seconde de votre forfait |
X-RateLimit-Remaining | 4 | Requêtes restantes dans la fenêtre en cours |
X-RateLimit-Reset | 1785200001 | Heure Unix de réinitialisation de la fenêtre |
X-Quota-Limit | 5000000 | Quota d’appels sur la période de 30 jours |
X-Quota-Remaining | 4815799 | Appels restants sur la période |
X-Quota-Reset | 1786492800 | Heure Unix de réinitialisation du quota |
Retry-After | 1 | Secondes à attendre avant de réessayer, sur 429 et 503 |
La fenêtre de requêtes par seconde dure une seconde ; dans une réponse normale, X-RateLimit-Reset pointe donc vers le début de la seconde suivante. Le quota restant de l’exemple : 5 000 000 − 184 201 = 4 815 799 appels, les mêmes chiffres que renvoie /account/usage.
L’endpoint /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": { … }
}
| Champ | Type | Signification |
|---|---|---|
plan | string | Forfait : trial, start, pro ou max |
calls_used | int | Appels utilisés sur la période en cours |
calls_limit | int | Quota d’appels par période |
rps_limit | int | Limite de requêtes par seconde |
freshness_sec | int | Retard des données, en secondes |
period_resets_at | int | Heure Unix de réinitialisation du quota |
L’endpoint est disponible sur tous les forfaits et décrit dans la section Utilisation. Appelez-le au démarrage d’un bot, pour vérifier le forfait et le quota restant avant de commencer à interroger.
Erreurs 429 : rate_limited et download_limited
| Réponse | Quand elle survient | Que faire |
|---|---|---|
429 rate_limited | Plus de requêtes par seconde que ne le permet votre forfait | Attendre la durée de Retry-After et espacer les requêtes |
429 rate_limited | Le quota de la période est épuisé | Attendre la réinitialisation ou changer de forfait |
429 rate_limited | Téléchargement complet de l’analytique de funding plus tôt qu’autorisé | Demander une tranche avec coin ou envoyer If-None-Match |
429 download_limited | Plus de 60 Mo de données compressées en 10 secondes | Attendre la durée de Retry-After, restreindre la requête avec des filtres |
Le code d’état 429 Too Many Requests est défini dans la RFC 6585, où Retry-After est facultatif. Genesis API l’envoie avec chaque 429, toujours en secondes.
Les réponses de moins de 64 Ko ne comptent pas dans le volume de téléchargement, et interroger tous les jeux de données à la fraîcheur de votre forfait tient largement dans la limite. Les téléchargements complets de l’analytique de funding sans coin ont leur propre limite : /funding/analytics/summary et /funding/analytics/recent une fois par 60 secondes, /funding/analytics/daily une fois par 300 secondes et par clé. Les requêtes avec coin et les réponses 304 ne sont pas limitées ; les détails sont dans la section Analytique de funding.
Accès par forfait et 403 plan_restricted
| Forfait | Ce qui est ouvert |
|---|---|
| Trial | Arbitrage CEX (Spot – Spot, Spot – Futures, Futures – Futures), taux de financement (funding) et spread de funding, Fair – Last, CEX Pumps – Dumps, open interest, signaux IA, recherche de coins, /account/usage |
| Start | Tout Trial, plus les actions /arbitrage/stocks, les sections on-chain /onchain/{section}, l’arbitrage des marchés de prédiction en modes exact et dutch, l’état des plateformes |
| Pro et Max | Tous les endpoints : DEX – Spot, DEX – Futures, Crosschain, DEX Dumps, carnets d’ordres, analytique de funding, analytique des marchés de prédiction, smart money, transactions, traders, modes llm et sport, swaps DEX, analytique OnChain et coin |
Un endpoint hors de votre forfait renvoie 403, tout comme une requête mode=sport vers /predictions/arbitrage sur Start :
{
"success": false,
"error": {
"code": "plan_restricted",
"message": "This endpoint is not included in your plan."
}
}
Un 403 ne consomme pas de quota. Le réessayer ne sert à rien : seul un forfait supérieur ouvre l’accès.
Dimensionner son forfait selon la charge
Exemple d’illustration : un bot interroge trois endpoints, /arbitrage/spot-spot, /funding/spread et /market/open-interest, toutes les 10 secondes, 24 h/24.
- Requêtes par seconde : 3 / 10 = 0,3 en moyenne. Si les trois partent en même temps, elles tombent dans la même seconde, et Trial et Start renvoient
429pour celles en trop. - Appels par jour : 86 400 / 10 = 8 640 interrogations, 8 640 × 3 = 25 920 appels.
- Appels par 30 jours : 25 920 × 30 = 777 600. C’est plus que le quota de Trial, 500 000 ; sur Start, 777 600 / 2 000 000 = 38,88 % du quota.
- Fraîcheur : sur Start, l’instantané se met à jour toutes les 30 secondes, soit 86 400 / 30 = 2 880 fois par jour. Les données nouvelles viennent de 2 880 × 3 × 30 = 259 200 appels, et les 777 600 − 259 200 = 518 400 autres renvoient la même chose.
Le même bot interrogeant à la fraîcheur de chaque forfait :
| Fraîcheur et interrogation | Appels par 30 jours | Forfait | Part du quota |
|---|---|---|---|
| Toutes les 60 s | 129 600 | Trial | 26 % |
| Toutes les 30 s | 259 200 | Start | 13 % |
| Toutes les 10 s | 777 600 | Pro | 16 % |
| Toutes les 5 s | 1 555 200 | Max | 16 % |
Interroger toutes les 10 secondes a du sens à partir de Pro : 777 600 / 5 000 000 = 15,552 % du quota, et la limite de 5 requêtes par seconde permet d’envoyer les trois d’un coup. Si le bot s’accommode de données vieilles de 30 secondes, Start avec une interrogation toutes les 30 secondes coûte 259 200 / 2 000 000 = 12,96 % du quota.
Interroger sans appels gaspillés : ETag et Retry-After
Votre forfait reçoit un nouvel instantané toutes les meta.freshness_sec secondes, et interroger plus vite renvoie le même instantané avec le même meta.updated_at. Sans l’en-tête If-None-Match, une telle réponse est un 200 et un appel consommé. Avec lui, le serveur répond 304 sans corps : le quota reste intact, mais un créneau de la limite par seconde est pris.
Un ETag ne vient pas avec toutes les réponses. Les jeux de données complets le renvoient, c’est-à-dire les requêtes sans filtres, comme /funding/spread dans l’exemple ci-dessous. Une réponse filtrée (coin, min_spread et d’autres) n’a pas d’ETag, et chaque interrogation coûte un appel : les filtres économisent du trafic, l’ETag économise du quota. Les nouvelles tentatives et la compression sont traitées dans comment interroger une API efficacement et dans le guide des réponses et erreurs.
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30
while True:
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
r = requests.get(URL, headers=headers, timeout=15)
if r.status_code in (429, 500, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 600: # le quota est épuisé, on s’arrête ici
raise SystemExit(f"Quota épuisé, réinitialisation dans {wait} s")
time.sleep(wait)
continue
r.raise_for_status() # une nouvelle tentative ne corrige pas 401 ni 403
left = r.headers.get("X-Quota-Remaining") # peut être absent
if left is not None and int(left) < 10_000:
print("Quota bientôt épuisé :", left)
if r.status_code == 200: # avec 304, les données n’ont pas changé
etag = r.headers.get("ETag")
body = r.json()
pause = body["meta"].get("freshness_sec", pause)
print(body["meta"]["count"], "coins dans la réponse")
time.sleep(pause)
Changer et renouveler son forfait
- Un nouveau forfait prend effet juste après le paiement : nouvelles limites et fraîcheur, le quota repart de zéro et le reste de l’ancien forfait est perdu. Le site vous prévient avant le paiement.
- Renouveler le même forfait ajoute des jours à la durée et ne réinitialise pas le quota : la période de 30 jours en cours se poursuit.
- Votre clé reste la même quand vous changez ou renouvelez un forfait, vos programmes n’ont donc pas besoin de mise à jour.
- La remise de période s’applique au prix mensuel : Pro pour 6 mois coûte 100 $ × 0,8 × 6 = 480 $ au lieu de 600 $, pour 3 mois 100 $ × 0,9 × 3 = 270 $.
Comment obtenir et conserver la clé est expliqué dans le guide de la clé Genesis API.
Questions et réponses
Que se passe-t-il si le quota s’épuise avant la fin de la période ?
Le serveur renvoie 429 rate_limited avec Retry-After jusqu’à la réinitialisation du quota, et rien n’est facturé. Attendez la nouvelle période ou payez un forfait supérieur : il prend effet immédiatement, avec un quota neuf.
Les réponses 304 et les erreurs comptent-elles dans les limites ?
Pas dans le quota : seul 200 le consomme. Elles comptent en revanche dans la limite de requêtes par seconde : les réponses 304 et les erreurs occupent des créneaux dans la fenêtre par seconde.
Comment vérifier le quota restant sans consommer d’appel ?
Lisez X-Quota-Remaining dans une réponse de données ou appelez /account/usage : cette requête ne consomme pas d’appel. La ligne des appels utilisés dans votre profil montre aussi la consommation.
Puis-je contourner la limite avec plusieurs clés ?
Non. Chaque compte reçoit une clé, les limites sont comptées par clé, et changer d’adresse IP ne les modifie pas. Ouvrir plusieurs comptes pour contourner les limites enfreint les règles ; si vous avez besoin de plus, passez à un forfait supérieur.