Limites d’usage

#Les limites par offre

Quatre offres, quatre jeux de limites. L’offre Entreprise se négocie ; elle n’a pas de valeur par défaut.

Le catalogue documente 121 chemins, dont deux sondes hors quota (/v1/health et /v1/status) décomptées pour personne. Seule la première répond sans clé.

#Limite de débit et quota mensuel

Deux compteurs, tous deux par compte : pas par adresse, pas par clé. Renouveler une clé, ou répartir le trafic sur plusieurs adresses, ne change ni l’un ni l’autre.

• La limite de débit se mesure par minute, avec une rafale tolérée : quelques requêtes d’un coup passent, au-delà les suivantes sont lissées puis refusées. Le refus est un 429 avec Retry-After: 1.
• Le quota mensuel compte chaque requête soumise à quota, sur le mois calendaire en UTC, et repart de zéro le premier jour du mois. Une fois épuisé, il renvoie un 429 avec Retry-After: 3600 jusqu’à son renouvellement, ou jusqu’à un changement d’offre, qui est immédiat.

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-Deny-Reason: rate

{"status":"error","timestamp":1775648290510,"detail":"Debit depasse : votre offre autorise un nombre limite de requetes par minute.","retry_after":1}

L’en-tête X-Deny-Reason porte la raison de tout refus lié à l’offre (rate, quota, family, websocket ou key), et le corps la redit en clair dans detail. Il n’y a pas d’en-tête de compteur sur les réponses normales : l’état du quota se lit dans la console, qui prévient à 80 % puis à la première requête refusée.

#Les familles de données

Chaque endpoint appartient à exactement une famille de quota, et chaque offre ouvre un ensemble de familles. Une famille absente de votre offre l’est sur tous les canaux : la route REST renvoie un 403, le snapshot retire ses champs et les liste dans out_of_plan_fields, le flux WebSocket refuse le canal.

HTTP/1.1 403 Forbidden
X-Deny-Reason: family

{"status":"error","timestamp":1775648290510,"detail":"Cette famille de donnees n est pas incluse dans votre offre."}

La correspondance entre les treize familles du catalogue et ces douze familles de quota est donnée sur la page des tarifs ; celle entre un chemin et sa famille est dans le catalogue des endpoints.

#Jusqu’où remonte l’historique

La profondeur d’historique dépend de l’offre et de l’unité de temps. C’est une fenêtre glissante depuis maintenant, pas un plafond par requête : hier est hors offre en bougies 1 min sur Free, quelle que soit la pagination.

• 30m suit la fenêtre de 1h, 1w celle de 1d : « Complet » vaut donc aussi pour la semaine partout où il vaut pour le jour.
• Les routes sans unité de temps (historiques since_ms / until_ms, séries quotidiennes, funding) sont bornées par la fenêtre 1h de l’offre : 24 h en Free, 1 semaine en Traders, 30 jours en Financial, 90 jours en Startup.
• Les routes tick par tick (/v1/raw/spot-ticks, /v1/raw/futures-ticks, /v1/raw/trades) ont leur propre fenêtre, la ligne ticks ci-dessus, et ne sont ouvertes que là où la famille l’est : 1 h en Financial, 24 h en Startup.
• Le contrôle porte sur la borne la plus ancienne réellement atteinte : limit multiplié par la durée de l’unité de temps, ou since_ms, ou un until_ms déjà au-delà de la fenêtre.

Le dépassement renvoie un 403 explicite, jamais une réponse tronquée : le detail dit ce qui a été demandé, ce que l’offre autorise et la limit maximale utilisable.

HTTP/1.1 403 Forbidden

{"detail":"Profondeur d'historique hors offre : 30 jour(s) demandes en 1m, votre offre en autorise 1 heure(s) (soit limit=60 au maximum sur ce timeframe, et aucune borne since_ms/until_ms au-dela de cette fenetre)."}

#Connexions au flux

Le flux WebSocket est ouvert à partir de Traders. La clé est vérifiée à la poignée de main : une offre sans le flux reçoit un 403 et la connexion n’est pas établie. Le plafond de connexions simultanées vaut pour tout le compte, toutes clés confondues ; la connexion de trop est fermée avec le code 4003 et le plafond dans la raison.

Une connexion qui reste abonnée coûte bien moins qu’une interrogation répétée : si vous appelez le même endpoint chaque seconde, le flux est la bonne réponse. Voir Flux WebSocket.

#Plafonds de profondeur

Indépendamment de l’offre, chaque route borne sa limit. Ces plafonds sont techniques ; la fenêtre de l’offre s’applique par-dessus, et c’est la plus stricte des deux qui compte.

#Que faire

import time
import httpx


def get(client: httpx.Client, path: str, **params):
    """Retry on the delay the server announces, never on a 403."""
    for attempt in range(4):
        response = client.get(path, params=params)

        if response.status_code in (429, 503):
            # The server knows when it will be ready: do not invent a delay.
            # On an exhausted monthly quota (X-Deny-Reason: quota), Retry-After
            # is an hour: no point insisting, the counter restarts on the 1st.
            wait = float(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue

        # 403: the request is outside the plan (family, depth, key). Replaying
        # it as is will produce exactly the same response.
        response.raise_for_status()
        return response.json()

    raise RuntimeError("the service is still unavailable after 4 attempts")

# Three calls where one is enough.
GET /v1/funding/rate?symbol=BTCUSDT
GET /v1/basis?symbol=BTCUSDT
GET /v1/oi/delta?symbol=BTCUSDT

# The same result, in one request (from Traders upwards).
GET /v1/snapshot?symbol=BTCUSDT&funding_rate_8h=true&basis=1&oi_delta=1