应用与 AI 智能体的使用限制

#各方案的限制

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

目录中记录了 138 条路径。其中三条从不计入配额，仅受速率限制约束：/v1/health（唯一无需密钥的接口）、/v1/limits（你的密钥的限制），以及 POST /v1/ws/token（短期 WebSocket 令牌，遵循数据流权限）。/v1/status 按一次价格与成交量请求计数。合约在 x-family 中给出每个接口所属的市场数据族。

#速率限制与月度配额

两个计数器，都按账户计算：既不按地址，也不按密钥。轮换密钥或把流量分散到多个地址，都不会改变其中任何一个。在它们之前，边缘网关还按 IP 地址做防洪：每秒 20 个请求，突发上限 40 个，超出时返回 429 edge_rate_limited 并带 Retry-After: 1。它只拦截洪泛：共享出口地址（NAT、serverless）请据此规划。

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

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

X-Deny-Reason 响应头给出任何与方案相关的拒绝原因（rate_limited、quota_exceeded、plan_family、plan_websocket、missing_api_key、invalid_api_key 或 history_depth），正文在 error.code 中指明该原因（rate_limited、quota_exceeded、plan_family、plan_websocket、invalid_api_key、history_depth），并附英文的 error.message。所有使用计量密钥（控制台中创建的每把密钥都是）的响应都带有 IETF 标准响应头，分为两项策略：RateLimit-Policy: "rate";q=…;w=…, "quota";q=…;w=… 与 RateLimit: "rate";r=…;t=…, "quota";r=…;t=…。quota_exceeded 的 r 即月度配额余量。控制台显示同样的状态，达到 80% 时会提醒，首次请求被拒时再次提醒。

#市场数据族

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

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

目录中十个类别与这十二个市场数据族之间的对应关系见价格页面；每个接口所属的市场数据族见端点目录以及合约（x-family，即 GET /v1/limits 返回的标识符）。

#历史能回溯多远

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

• 30m 沿用 1h 的窗口，1w 沿用 1d 的窗口：因此凡是日线为“全部”的地方，周线也同样为“全部”。
• 没有周期参数的接口（since_ms / until_ms 历史）受方案 1h 窗口的限制：Free：24 小时, Traders：1 周, Financial：30 天, Startup：90 天。日度序列（每天一个点或更慢：Fear & Greed、链上、ETF、宏观）改为遵循 1d 行——标为“全部”的方案不受限制。
• 资金费率（费率与累计历史，八小时窗口，接受 since_ms / until_ms）遵循方案的 4h 窗口：Free：1 周, Traders：30 天, Financial：72 天, Startup：全部。
• 逐笔成交路由（/v1/trades/spot、/v1/trades/futures、/v1/trades/large、/v1/trades-kline/futures/seconds）有自己的窗口，即上方的 ticks 行，并且只在开放该市场数据族的套餐中可用：Financial：1 小时, Startup：24 小时。快照中对应的字段（trades_spot、trades_futures、trades_kline_futures_seconds）在时间上受同一窗口限制。
• 校验针对实际到达的最早边界：limit 乘以周期时长，或 since_ms，或已超出窗口的 until_ms。

超出范围会返回明确的 403，绝不会返回截断的响应：error.message 会说明请求了什么、方案允许什么，以及可使用的最大 limit。你自己填写的边界（since_ms、until_ms）享有两分钟的时钟偏差容忍；单独的 limit 则没有。既不带 limit 也不带 since_ms 时不会被拒绝：结果页只是停在窗口边缘，此时 next 为 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"
    }
  }
}

#数据流连接

WebSocket 数据流从 Traders 方案起开放。密钥在握手时校验：不含数据流的方案收到 403，连接不会建立。同时连接上限按整个账户（所有密钥合计）计算；超出的连接以代码 4003 关闭，原因中给出上限（消费过慢的客户端以 4005 关闭）。握手时的 503 与你的方案无关：表示数据流服务已达容量上限（所有账户合计）。

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

#深度上限

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

#如何应对

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