Limites d’usage des apps et agents IA

#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 138 chemins. Trois ne sont jamais décomptés du quota, seule la limite de débit s’applique : /v1/health, le seul qui répond sans clé, /v1/limits, les limites de votre clé, et POST /v1/ws/token, le jeton WebSocket éphémère (il suit le droit au flux). /v1/status compte comme une requête prix et volume. Le contrat nomme la famille de chaque route dans x-family.

#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. En amont, la passerelle applique un anti-flood par adresse IP : 20 requêtes par seconde, rafales de 40, refusées en 429 edge_rate_limited avec Retry-After: 1. Il n’arrête que les déferlements : dimensionnez-y une adresse de sortie partagée (NAT, serverless).

• 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 rate_limited dont le Retry-After donne les secondes avant la prochaine requête permise (la même valeur que error.details.retry_after_s).
• 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 dont le Retry-After donne les secondes jusqu’à son renouvellement, ou jusqu’à un changement d’offre, qui est immédiat.

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-Deny-Reason: rate_limited

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: your plan allows a limited number of requests per minute. Retry after the Retry-After delay.",
    "details": {
      "retry_after_s": 2
    }
  }
}

L’en-tête X-Deny-Reason porte la raison de tout refus lié à l’offre (rate_limited, quota_exceeded, plan_family, plan_websocket, missing_api_key, invalid_api_key ou history_depth), et le corps la nomme dans error.code (rate_limited, quota_exceeded, plan_family, plan_websocket, invalid_api_key, history_depth) avec un error.message en anglais. Toute réponse faite avec une clé comptée (toute clé créée dans la console) porte les en-têtes standard de l’IETF, en deux politiques : RateLimit-Policy: "rate";q=…;w=…, "quota";q=…;w=… et RateLimit: "rate";r=…;t=…, "quota";r=…;t=…. Le r de quota_exceeded est le quota mensuel restant. La console montre le même état, et prévient à 80 % puis à la première requête refusée.

#Les familles de données de marché

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: plan_family

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "plan_family",
    "message": "The 'options' data family is not included in your plan. GET /v1/limits lists the families of your key; https://bytnode.com/pricing lists the plans that open it."
  }
}

La correspondance entre les dix catégories du catalogue et ces douze familles de données de marché est donnée sur la page des tarifs ; la famille de chaque route est dans le catalogue des endpoints et dans le contrat (x-family, les identifiants que rend GET /v1/limits).

#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) 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 séries quotidiennes (un point par jour ou moins : Fear & Greed, on-chain, ETF, macro) suivent la ligne 1d — illimitées là où elle indique « Complet ».
• Le funding (historiques du taux et du cumul, fenêtres de huit heures, since_ms / until_ms acceptés) suit la fenêtre 4h de l’offre : 1 semaine en Free, 30 jours en Traders, 72 jours en Financial, complet en Startup.
• Les routes transaction par transaction (/v1/trades/spot, /v1/trades/futures, /v1/trades/large, /v1/trades-kline/futures/seconds) 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. Les champs correspondants du snapshot (trades_spot, trades_futures, trades_kline_futures_seconds) sont bornés dans le temps par la même fenêtre.
• 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 : l’error.message dit ce qui a été demandé, ce que l’offre autorise et la limit maximale utilisable. Les bornes que vous écrivez vous-même (since_ms, until_ms) bénéficient d’une tolérance de deux minutes pour l’écart d’horloge ; une limit seule, non. Sans limit ni since_ms, rien n’est refusé : la page s’arrête simplement au bord de la fenêtre, et next y vaut null.

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

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "history_depth",
    "message": "History depth beyond your plan: 30 day(s) requested on 1h, your plan allows 1 day(s) (i.e. at most limit=24 on this timeframe, and no since_ms/until_ms bound beyond that window).",
    "param": "limit",
    "details": {
      "window_s": 86400,
      "earliest_ms": 1791763200000,
      "max_limit": 24,
      "timeframe": "1h"
    }
  }
}

#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 (un client trop lent est fermé avec 4005). Un 503 à la poignée de main n’est pas lié à votre offre : il dit que le service de flux a atteint sa capacité, tous comptes confondus.

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  # pip install 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 == 429 and response.headers.get("X-Deny-Reason") == "quota_exceeded":
            # The monthly quota is spent: Retry-After counts the seconds until the 1st
            # of the month. Do not sleep for days: stop, or change plan.
            raise RuntimeError(response.json()["error"]["message"])

        if response.status_code in (429, 503):
            # The server knows when it will be ready: do not invent a delay.
            wait = float(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue

        body = response.json()
        if body["status"] == "error":
            # 401 / 403 / 422: the request itself is refused (key, plan, value).
            # Replaying it as is produces exactly the same response: keep the
            # stable code, it says what to change.
            raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')
        return body

    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/change?symbol=BTCUSDT

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