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 — qui ne sont comptées pour personne. Seule la première répond sans clé.

#Débit et quota mensuel

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

• Le 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. Épuisé, il rend un 429 avec Retry-After: 3600 jusqu’au renouvellement — ou jusqu’à un changement d’offre, 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 le motif de tout refus lié à l’offre — rate, quota, family, websocket ou key — et le corps le répète 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 rend 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 offres ; celle entre un chemin et sa famille se lit dans le catalogue des endpoints.

#Jusqu’où remonte l’historique

La profondeur d’historique dépend de l’offre et du pas 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 là où le jour l’est.
• Les routes sans pas 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, 7 jours en Traders, 30 jours en Financial, 90 jours en Startup.
• Le contrôle porte sur la borne la plus ancienne réellement atteinte — limit multiplié par la durée du pas, ou since_ms, ou un until_ms déjà au-delà de la fenêtre.

Un dépassement rend un 403 explicite, jamais une réponse tronquée : le detail dit ce qui a été demandé, ce que l’offre autorise et le limit maximal 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 au handshake : une offre sans flux reçoit un 403 et la connexion ne s’établit pas. Le plafond de connexions simultanées vaut pour le compte entier, toutes clés confondues ; la connexion de trop est fermée avec le code 4003 et le plafond dans le motif.

Une connexion qui reste abonnée est bien moins coûteuse que du sondage répété : si vous appelez le même endpoint toutes les secondes, le flux est la bonne réponse. Voir Flux WebSocket.

#Plafonds de profondeur

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

#Conduite à tenir

import time
import httpx


def get(client: httpx.Client, chemin: str, **params):
    """Reessaie sur le delai que le serveur annonce, jamais sur un 403."""
    for tentative in range(4):
        reponse = client.get(chemin, params=params)

        if reponse.status_code in (429, 503):
            # Le serveur sait quand il sera pret : ne pas inventer de delai.
            # Sur un quota mensuel epuise (X-Deny-Reason: quota), Retry-After
            # vaut une heure : inutile d'insister, le compteur repart le 1er.
            attente = float(reponse.headers.get("Retry-After", 2 ** tentative))
            time.sleep(attente)
            continue

        # 403 : la requete est hors offre (famille, profondeur, cle). La
        # rejouer telle quelle produira exactement la meme reponse.
        reponse.raise_for_status()
        return reponse.json()

    raise RuntimeError("le service reste indisponible apres 4 tentatives")

# Trois appels la ou un seul suffit.
GET /v1/funding/rate?symbol=BTCUSDT
GET /v1/basis?symbol=BTCUSDT
GET /v1/oi/delta?symbol=BTCUSDT

# Le meme resultat, en une requete (a partir de Traders).
GET /v1/snapshot?symbol=BTCUSDT&funding_rate_8h=true&basis=1&oi_delta=1