Genesis Arbitrage

Genesis Arbitrage · · 17 min de lecture

Comment interroger une API crypto sans dépasser les limites : ETag, gzip, filtres et nouvelles tentatives après un 429

En bref

  • Une API a généralement trois limites : requêtes par seconde, quota d’appels par période et volume de téléchargement. Pour Genesis API, cela donne de 1 à 15 requêtes par seconde, de 500 K à 10 M d’appels par 30 jours et 60 Mo de données compressées par 10 secondes et par clé.
  • Réglez l’intervalle de polling d’après meta.freshness_sec : interroger plus vite renvoie le même snapshot. If-None-Match transforme une répétition en 304 gratuit, gzip et les filtres réduisent le trafic, et un seul dataset complet au lieu d’une requête par coin économise des appels.
  • Réessayez 429 et 503 après Retry-After secondes ou, sans cet en-tête, avec un backoff exponentiel plus un jitter aléatoire. Un token bucket côté client garde votre rythme sous la limite, et les en-têtes X-RateLimit-* et X-Quota-* montrent la marge restante.

Pour interroger une API sans erreurs 429, calez vos requêtes sur trois limites à la fois : les requêtes par seconde, le quota d’appels de la période et le volume de données téléchargé. Cinq techniques suffisent : un intervalle non inférieur au rafraîchissement des données, des requêtes conditionnelles avec ETag, la compression gzip, des filtres plutôt que des téléchargements démesurés, et des nouvelles tentatives après la pause demandée par le serveur. Les chiffres et le code ci-dessous concernent Genesis API, une API REST de données du marché crypto, mais les techniques valent pour toute API HTTP, y compris celles des exchanges.

Trois limites d’une API : requêtes par seconde, quota et volume

Un rate limit par seconde attrape les rafales : un lot de requêtes envoyées d’un coup. Le quota attrape votre rythme moyen sur toute la période, et la limite de volume attrape les gros téléchargements même quand il y a peu de requêtes.

LimiteCe qui est comptéGenesis APIEn cas de dépassement
Requêtes par secondeChaque requête, y compris 304 et erreurs1 en Trial, 2 en Start, 5 en Pro, 15 en Max429 rate_limited, Retry-After: 1
Quota par périodeUniquement les réponses 200500 K, 2 M, 5 M, 10 M d’appels par 30 jours429 rate_limited, Retry-After jusqu’à la réinitialisation du quota
Volume de téléchargementRéponses compressées de 64 Ko et plus60 Mo par 10 secondes et par clé, sur tous les plans429 download_limited jusqu’à la fin de la fenêtre

Genesis API ne facture jamais les requêtes au-delà d’une limite : un 429 ne consomme aucun quota et ne coûte rien. Toutes les règles figurent dans le guide des limites de Genesis API et dans la section Plans et limites de la documentation.

Les API des exchanges peuvent être plus complexes. Binance compte le poids des requêtes par adresse IP, et chaque endpoint a son propre poids. Un client qui continue d’envoyer des requêtes après un 429 reçoit un bannissement automatique de l’IP avec le statut 418, et les récidivistes des bannissements plus longs (documentation Binance).

Intervalle de polling : combien d’appels vous utilisez en 30 jours

Interroger plus vite que le rafraîchissement des données n’apporte que des répétitions. Le cœur de Genesis Arbitrage rafraîchit les données chaque seconde, tandis que la sortie de l’API pour votre plan est rafraîchie une fois toutes les meta.freshness_sec secondes : 60 en Trial, 30 en Start, 10 en Pro et 5 en Max. C’est la fraîcheur des données de votre plan et le plancher de votre intervalle de polling. Genesis API n’a ni WebSocket ni webhooks : les données s’obtiennent par polling en REST.

Exemple illustratif : un bot sur le plan Start — 50 $ par mois, 2 M d’appels, 2 requêtes par seconde, fraîcheur de 30 s — interroge quatre endpoints : /arbitrage/spot-spot, /arbitrage/spot-futures, /funding/spread et /market/open-interest.

IntervalleAppels par 30 joursPart du quota StartRépétitions d’un snapshot
60 s172 8008,64 %aucune
30 s345 60017,28 %aucune
10 s1 036 80051,84 %2 sur 3
5 s2 073 600103,68 %5 sur 6

Interroger toutes les 5 secondes épuise le quota au 29e jour : 4 × 86 400 / 5 = 69 120 appels par jour, et 2 000 000 / 69 120 ≈ 28,9 jours. Cinq réponses sur six répètent un même snapshot avec le même meta.updated_at, et sans If-None-Match chacune coûte un appel.

À une interrogation toutes les 30 secondes, le rythme moyen est de 4 / 30 ≈ 0,13 requête par seconde. Mais quatre requêtes envoyées en même temps tombent dans la même seconde, et deux d’entre elles reçoivent un 429. Si vous avez besoin de données plus fraîches que 30 secondes, la réponse est un plan avec un freshness_sec plus bas : Pro rafraîchit le snapshot toutes les 10 secondes, Max toutes les 5.

Requêtes conditionnelles : ETag, If-None-Match et 304

Un ETag est une étiquette de version d’une réponse. Le client la conserve et la renvoie dans l’en-tête If-None-Match de sa requête suivante vers la même URL ; si la version n’a pas changé, le serveur répond 304 Not Modified. Selon la RFC 9110, un 304 s’arrête après les en-têtes et n’a pas de corps : vous utilisez donc votre propre copie des données.

Sur Genesis API, un 304 ne consomme aucun quota mais occupe tout de même un créneau dans la limite de requêtes par seconde. Seuls les datasets complets sans filtres reçoivent une étiquette. Les réponses aux requêtes avec coin, exchange, min_spread ou d’autres filtres, ainsi que /orderbooks/book et /orderbooks/coin/{coin}, sont construites à chaque requête et arrivent sans ETag.

ETag économise du quota là où les données changent moins souvent que vous ne les demandez. L’étiquette des spreads change à chaque snapshot : si vous interrogez une fois par freshness_sec, presque toutes les réponses sont des 200.

Exemple illustratif en Pro : les sommes quotidiennes de l’analytique du funding, /funding/analytics/daily, sont régénérées toutes les heures ; une fois un an d’historique accumulé, la section complète pèse environ 12 Mo en gzip, et sans coin elle n’est servie qu’une fois par 300 secondes au plus. Interroger toutes les 300 secondes fait 2 592 000 / 300 = 8640 requêtes en 30 jours. Avec If-None-Match, la section est téléchargée 30 × 24 = 720 fois, et les 8640 − 720 = 7920 autres réponses reviennent en 304.

Résultat : 720 appels au lieu de 8640, et environ 8,6 Go de trafic au lieu de 104 Go. Les réponses 304 ne comptent pas dans la limite de téléchargement complet.

Filtres et coin : ce qui économise des appels et ce qui économise du trafic

Un filtre réduit la réponse mais pas le nombre d’appels : le quota compte les réponses, et une requête avec coin=BTC coûte autant que le dataset complet. Le choix dépend donc de ce qui s’épuise en premier, les appels ou le trafic.

Exemple illustratif en Start : un bot suit le funding de cinq coins. Cinq requêtes vers /funding/rates avec coin toutes les 30 secondes font 5 × 86 400 = 432 000 appels en 30 jours, plus cinq requêtes par cycle face à une limite de 2 par seconde. Un seul /funding/rates complet, avec les coins triés dans le code, coûte 86 400 appels, cinq fois moins, et reçoit un ETag.

TâcheComment demanderCe qui est économisé
Plusieurs coins d’un même datasetDataset complet avec If-None-Match, filtre dans le codeAppels : une requête au lieu de plusieurs
Un coin d’une section lourdeLe paramètre coinTrafic et limite de volume
Lignes au-dessus d’un seuilmin_spread, min_volumeTrafic, mais chaque interrogation est un appel
Une section lente en entierDataset complet avec If-None-MatchAppels et trafic

Les sections les plus lourdes sont celles de l’analytique du funding : la synthèse complète fait environ 600 Ko en gzip, les paiements sur 7 jours environ 1 Mo et les sommes quotidiennes jusqu’à 12 Mo (endpoints de funding). Une tranche d’un seul coin avec coin échappe à la limite de téléchargement complet, qui est d’une fois par 60 secondes pour la synthèse et les paiements et d’une fois par 300 pour les sommes quotidiennes.

Compression gzip

La compression réduit le nombre d’octets sur le réseau. Le client la demande avec Accept-Encoding: gzip, et le serveur répond avec un corps compressé et un en-tête Content-Encoding: gzip. Le requests de Python ajoute gzip à Accept-Encoding et décompresse la réponse tout seul ; curl fait de même avec --compressed.

Sur Genesis API, la compression est liée à une limite : le volume de téléchargement est compté en données compressées, 60 Mo par 10 secondes et par clé, et les réponses de moins de 64 Ko ne sont pas comptées. Les datasets complets et les grosses réponses arrivent en gzip quand le client le demande (réponses et erreurs de Genesis API). Pour voir combien d’octets de corps ont réellement traversé le réseau, utilisez la variable size_download de curl :

# octets du corps sur le réseau avec et sans gzip ; chaque requête est un appel
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"

Réessayer après un 429 : Retry-After et backoff avec jitter

HTTP 429 Too Many Requests est la réponse du serveur à un client qui a dépassé une limite. Selon la RFC 6585, la réponse peut porter un en-tête Retry-After, et selon la RFC 9110 sa valeur est soit un nombre de secondes, soit une date. Genesis API envoie Retry-After avec chaque 429 et 503, en secondes.

Une nouvelle tentative sans pause reçoit presque toujours la même erreur et occupe un autre créneau de la fenêtre par seconde. S’il y a un Retry-After, attendez aussi longtemps que le serveur le demande. S’il n’y en a pas, attendez exponentiellement plus longtemps après chaque échec : jusqu’à 1, 2, 4, 8 secondes.

Le jitter, un ajout aléatoire à la pause, compte quand il y a beaucoup de clients : sans lui, tous ceux qui ont reçu une erreur dans la même seconde réessaient aussi dans la même seconde. La fonction backoff choisit une pause aléatoire entre zéro et le palier courant et ajoute une fraction de seconde à Retry-After. fetch réessaie 429, 500 et 503, et s’arrête quand la pause dépasse 10 minutes : c’est à cela que ressemble un quota épuisé.

import os
import random
import time

import requests

BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session()  # réutilise la connexion TCP, gzip activé
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # path -> (ETag, data) : datasets complets uniquement


def backoff(attempt, retry_after=None, cap=60.0):
    """Pause avant une nouvelle tentative, en secondes."""
    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 vers l’API : renvoie (data, en-têtes de la réponse)."""
    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:  # même snapshot, aucun quota consommé
            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:  # c’est à cela que ressemble un quota épuisé
                raise RuntimeError(f"le quota se réinitialise dans {wait:.0f} s")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403, 404, 410 : ne pas réessayer
        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} : pas de réponse après {tries} tentatives")
RéponsePauseNouvelle tentative
429 rate_limited, par secondeRetry-After: 1 plus une fraction de secondeOui
429 rate_limited, quotaJusqu’à la réinitialisation du quota, parfois des joursNon
429 download_limitedRetry-After, jusqu’à la fin de la fenêtreOui, avec des requêtes plus étroites
503 snapshot_not_readyRetry-AfterOui
500, timeout, connexion coupéeExponentielle avec jitterOui
400, 401, 403, 404, 410—Non, corrigez la requête

Vous distinguez un quota épuisé de la limite par seconde grâce à Retry-After : une seconde contre des heures ou des jours avant la réinitialisation, avec Monthly call quota exceeded. dans le corps de la réponse. Les codes et corps d’erreur sont dans la section Erreurs de la documentation.

Limiteur côté client : token bucket

Une nouvelle tentative traite un 429 ; un limiteur côté client l’évite. Un token bucket fonctionne ainsi : les jetons arrivent à rate par seconde, chaque requête en prend un, et un seau vide vous fait attendre. La capacité, burst, fixe combien de requêtes peuvent partir d’affilée sans pause.

import time


class TokenBucket:
    """Au plus rate requêtes par seconde, jusqu’à burst d’affilée."""

    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)

Prenez la limite dans le champ rps_limit de /account/usage (la section Utilisation) ou dans l’en-tête X-RateLimit-Limit. Réglez le rythme un peu sous la limite, par exemple 0.9 * rps_limit : la latence réseau est irrégulière, et des requêtes envoyées à une demi-seconde d’écart peuvent arriver plus rapprochées au serveur.

Surveillance : les en-têtes X-RateLimit-* et X-Quota-*

Une réponse de données porte l’état de vos limites : X-RateLimit-Remaining et X-RateLimit-Reset indiquent ce qui reste dans la fenêtre par seconde et quand elle se réinitialise, tandis que X-Quota-Remaining, X-Quota-Limit et X-Quota-Reset indiquent le quota restant, sa taille et l’heure unix de sa réinitialisation. Plus utile qu’un reste isolé, le rythme : quelle part du quota est consommée à ce stade de la période.

PERIOD = 30 * 86400  # Genesis API compte le quota par 30 jours


def watch(h):
    """Vérifie la marge des limites d’après les en-têtes de la réponse."""
    if h.get("X-RateLimit-Remaining") == "0":  # fenêtre épuisée
        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  # les réponses 429 n’ont pas d’en-têtes X-Quota-*
    used = 1 - left / limit
    passed = 1 - (reset - time.time()) / PERIOD
    if used > passed + 0.05:
        print(f"le quota prend de l’avance : {used:.0%} utilisé"
              f" alors que {passed:.0%} de la période s’est écoulée")

La fonction attend la réinitialisation de la fenêtre quand sa limite est atteinte, et prévient quand la consommation du quota devance le calendrier de plus de 5 points de pourcentage. Exemple illustratif : 70 % du quota est consommé au 15e jour, donc au même rythme les appels s’épuisent à 15 / 0,7 ≈ 21,4 jours de la période. /account/usage donne les mêmes chiffres sans en-têtes : calls_used, calls_limit et period_resets_at.

Un planning pour plusieurs endpoints

Avec plusieurs endpoints, chacun a son propre intervalle, et les premières requêtes sont étalées pour ne pas partir en lot. Choisissez l’intervalle selon la tâche, mais jamais en dessous de freshness_sec : les spreads demandent la cadence complète de votre plan, alors que pour beaucoup de stratégies une minute suffit pour le funding et l’open interest.

import heapq

usage, _ = fetch("/account/usage")  # ne consomme pas d’appel
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])

JOBS = {  # path -> intervalle de polling, 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))

En Start, cela fait 86 400 + 43 200 + 43 200 = 172 800 appels en 30 jours, soit 8,64 % du quota : spreads toutes les 30 secondes, funding et open interest toutes les 60. Les premières requêtes partent à 30 / 3 = 10 secondes d’intervalle, après quoi chaque endpoint garde son propre rythme, et bucket.take() protège des collisions. Un bot construit sur ce polling, avec des alertes Telegram, est présenté dans Bot d’arbitrage crypto en Python.

Que faire en cas de 503 et d’erreurs serveur

Selon la RFC 9110, 503 Service Unavailable signifie une surcharge temporaire ou une maintenance, et le serveur peut suggérer une pause dans Retry-After. Sur Genesis API, c’est 503 snapshot_not_ready : les données sont en cours de reconstruction ou leur source redémarre. Réessayez après Retry-After secondes ; la pause est généralement de quelques secondes.

Tant qu’il n’y a pas de réponse fraîche, votre bot détient toujours les données de la dernière interrogation, et ces données vieillissent. Avant d’envoyer un signal, comparez meta.updated_at à l’heure actuelle : une paire issue d’un snapshot vieux d’une minute a peut-être déjà disparu sur l’exchange. Les autres risques sont traités dans la leçon Risques de l’automatisation.

Réessayez 500 internal_error, les timeouts et les connexions coupées avec un backoff exponentiel. Si l’erreur persiste, contactez le support avec la valeur de X-Request-Id, l’heure de la requête en UTC, l’endpoint et le code de statut. N’envoyez jamais votre clé.

Questions et réponses

Combien de requêtes par seconde puis-je envoyer à Genesis API ?

Autant que votre plan le permet : 1 en Trial, 2 en Start, 5 en Pro et 15 en Max. La limite est par clé et inclut les réponses 304 et les erreurs. La valeur de votre plan figure dans l’en-tête X-RateLimit-Limit et dans le champ rps_limit de /account/usage.

Les erreurs et les réponses 304 comptent-elles dans mon quota ?

Non. Seule une réponse 200 consomme du quota ; 304, 429, 503 et les autres erreurs sont gratuites et ne coûtent rien. Elles occupent en revanche des créneaux dans la limite de requêtes par seconde : des nouvelles tentatives sans pause déclenchent donc de nouveaux 429.

Comment rester sous 60 Mo par 10 secondes ?

Activez gzip : la limite compte les données compressées. Envoyez If-None-Match avec les datasets complets : un 304 n’a pas de corps. Prenez les sections lourdes, comme l’analytique du funding, en tranche par coin, et ne téléchargez pas le même dataset complet plus souvent que freshness_sec. Les réponses de moins de 64 Ko ne comptent pas, et d’après la documentation, interroger chaque dataset à la fraîcheur de votre plan tient largement sous la limite.

Que signifie une erreur 429 Too Many Requests ?

Le serveur a rejeté la requête parce que le client a dépassé une limite dans une fenêtre de temps. La réponse peut porter Retry-After, le nombre de secondes à attendre ; sans lui, doublez la pause après chaque échec. Sur Genesis API, un 429 s’accompagne du code rate_limited ou download_limited.