Usage limits

#The limits by plan

Four plans, four sets of limits. The Enterprise plan is negotiated; it has no default value.

The catalogue documents 121 paths, two of which are out-of-quota probes (/v1/health and /v1/status) counted for nobody. Only the first answers without a key.

#Rate limit and monthly quota

Two counters, both per account: not per address, not per key. Rotating a key, or spreading the traffic over several addresses, changes neither one nor the other.

• The rate limit is measured per minute, with a tolerated burst: a few requests at once go through, beyond that the following ones are smoothed then refused. The refusal is a 429 with Retry-After: 1.
• The monthly quota counts every request subject to quota, over the calendar month in UTC, and restarts from zero on the first day of the month. Once exhausted, it returns a 429 with Retry-After: 3600 until it renews, or until a plan change, which is immediate.

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}

The X-Deny-Reason header carries the reason for any refusal tied to the plan (rate, quota, family, websocket or key), and the body repeats it in plain words in detail. There is no counter header on normal responses: the state of the quota is read in the console, which warns at 80 % then at the first refused request.

#The data families

Every endpoint belongs to exactly one quota family, and every plan opens a set of families. A family missing from your plan is missing on every channel: the REST route returns a 403, the snapshot removes its fields and lists them in out_of_plan_fields, the WebSocket stream refuses the channel.

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."}

The mapping between the thirteen families of the catalogue and these twelve quota families is given on the plans page; the one between a path and its family is in the endpoint catalogue.

#How far back the history goes

History depth depends on the plan and on the timeframe. It is a rolling window from now, not a per-request ceiling: yesterday is outside the plan in 1 min candles on Free, whatever the pagination.

• 30m follows the window of 1h, 1w that of 1d: “Full” therefore also holds for the week wherever it holds for the day.
• Routes without a timeframe (since_ms / until_ms histories, daily series, funding) are bounded by the 1h window of the plan: 24 h on Free, 1 week on Traders, 30 days on Financial, 90 days on Startup.
• Tick-by-tick routes (/v1/raw/spot-ticks, /v1/raw/futures-ticks, /v1/raw/trades) have their own window, the ticks row above, and are only open where the family is: 1 h on Financial, 24 h on Startup.
• The check bears on the oldest bound actually reached: limit multiplied by the duration of the timeframe, or since_ms, or an until_ms already beyond the window.

Going over returns an explicit 403, never a truncated response: the detail says what was asked for, what the plan allows and the maximum usable limit.

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)."}

#Stream connections

The WebSocket stream is open from Traders upwards. The key is checked at the handshake: a plan without the stream receives a 403 and the connection is not established. The ceiling on simultaneous connections holds for the whole account, all keys together; the connection too many is closed with code 4003 and the ceiling in the reason.

A connection that stays subscribed costs far less than repeated polling: if you call the same endpoint every second, the stream is the right answer. See WebSocket stream.

#Depth ceilings

Independently of the plan, every route bounds its limit. These ceilings are technical; the window of the plan applies on top, and it is the stricter of the two that counts.

#What to do

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