使用限制

#各方案的限制

四个方案，四组限制。企业版需协商确定，没有默认值。

目录中记录了 121 条路径，其中两个是不计配额的探测接口（/v1/health 和 /v1/status），不计入任何人的用量。只有前者无需密钥。

#速率限制与月度配额

两个计数器，都按账户计算：既不按地址，也不按密钥。轮换密钥或把流量分散到多个地址，都不会改变其中任何一个。

• 速率限制按分钟计算，并允许一定突发：一次发出少量请求可以通过，超过后后续请求会被平滑处理，然后被拒绝。拒绝时返回 429，并带 Retry-After: 1。
• 月度配额按 UTC 自然月统计每一个计入配额的请求，并在每月第一天清零。用尽后，在配额重置或更换方案（即时生效）之前，都会返回 429 并带 Retry-After: 3600。

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}

X-Deny-Reason 响应头给出任何与方案相关的拒绝原因（rate、quota、family、websocket 或 key），正文的 detail 中也会用文字说明。正常响应中没有计数类响应头：配额状态在控制台中查看，达到 80% 时提醒，首次请求被拒时再次提醒。

#数据族

每个端点恰好属于一个配额族，每个方案开放一组数据族。方案中缺少的数据族在所有通道上都不可用：REST 接口返回 403，快照会移除其字段并在 out_of_plan_fields 中列出，WebSocket 数据流会拒绝该频道。

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

目录中十三个数据族与这十二个配额族之间的对应关系见价格页面；路径与数据族之间的对应关系见端点目录。

#历史能回溯多远

历史深度取决于方案和周期。它是一个从当前时刻起的滚动窗口，而不是每次请求的上限：在 Free 方案中，无论如何分页，昨天的 1 分钟 K 线都超出方案范围。

• 30m 沿用 1h 的窗口，1w 沿用 1d 的窗口：因此凡是日线为“全部”的地方，周线也同样为“全部”。
• 没有周期参数的接口（since_ms / until_ms 历史、日度序列、资金费率）受方案 1h 窗口的限制：Free：24 小时, Traders：1 周, Financial：30 天, Startup：90 天。
• 逐笔接口（/v1/raw/spot-ticks、/v1/raw/futures-ticks、/v1/raw/trades）有各自的窗口，即上表中的 ticks 行，并且只在开放该数据族的方案中可用：Financial：1 小时, Startup：24 小时。
• 校验针对实际到达的最早边界：limit 乘以周期时长，或 since_ms，或已超出窗口的 until_ms。

超出范围会返回明确的 403，绝不会返回截断的响应：detail 会说明请求了什么、方案允许什么，以及可使用的最大 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)."}

#数据流连接

WebSocket 数据流自 Traders 方案起开放。密钥在握手时校验：不含数据流的方案会收到 403，连接不会建立。同时连接数上限适用于整个账户，涵盖所有密钥；超出的连接以代码 4003 关闭，并在原因中给出上限。

保持订阅的连接比反复轮询划算得多：如果你每秒调用同一个端点，数据流才是正确的选择。见 WebSocket 数据流。

#深度上限

与方案无关，每个接口都会限制其 limit。这些上限是技术性的；方案的窗口叠加其上，以两者中更严格的为准。

#如何应对

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