速率限制

速率限制如何工作

Token101 实施多层速率限制，同时保护单个用户和平台整体：

1. RPM（每分钟请求数） — 固定 1 分钟窗口，按用户或 API Key 作用域
2. 并发限制 — 同时进行中的请求数上限
3. 消费上限（Spend Cap） — 周、月的积分（credits）消耗上限
4. 全局容量 — 每个模型的全平台 RPM 总量（基础设施保护）

各层按顺序依次检查。请求被拒绝时，响应头和 JSON 体会明确告知是哪一层限制生效以及何时重置。

RPM 限制

RPM 限制使用固定窗口限流器（1 分钟窗口）。作用域取决于套餐类型：

• 订阅用户：RPM 作用域为用户 ID — 所有 API Key 共享一个 RPM 桶
• PAYG 用户：RPM 作用域为每个 API Key — 各 Key 有独立的 RPM 限制

并发限制

并发限制控制同时进行中的请求数量。请求开始时获取租约，请求完成（成功或失败）时释放租约。

租约有 ~120 秒的安全 TTL。如果租约未被释放（如客户端断连），会自动过期以防止槽位耗尽。

消费上限（Spend Cap）

消费上限限制你在给定时间窗口内可消耗的积分数量，不受账户总余额影响。此限制在平台策略层执行，在请求到达模型之前生效。

标准套餐

HotPricing PAYG

消费上限窗口锚定订阅/购买周期（周与月）。更高的套餐等级会提升这些上限，完整对照见定价页。

全局容量

除单用户限制外，每个模型还有全平台 RPM 上限。当所有用户对某模型的请求总量超过此上限时，新请求会返回 429 错误。这用于在流量高峰时保护基础设施。

错误响应

HTTP 状态码

JSON 响应体

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Too many requests in current window."
  }
}

平台策略层拒绝时，error 内可能嵌套 detail 对象：

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Too many requests in current window.",
    "code": "rate_limit_exceeded",
    "detail": {
      "quotaWindow": {
        "rpm": {
          "scopeType": "user_id",
          "scopeId": "user_xyz",
          "used": 100,
          "limit": 100,
          "remaining": 0,
          "resetAt": "2026-04-26T14:25:00Z"
        }
      }
    }
  }
}

响应头

所有限流响应都包含标准头：

平台策略层响应包含额外的诊断头：

最佳实践

优先遵守 Retry-After — 始终等待指定秒数后再重试。然后叠加带抖动的指数退避，避免惊群效应。

使用 X-RateLimit-* 头 — 在客户端跟踪剩余配额。如果 X-RateLimit-Remaining 较低，在触达限制前主动降速。

按 API Key 拆分流量 — PAYG 用户的 RPM 按 Key 作用域隔离。为交互式流量和批处理流量使用不同的 Key，避免竞争同一个 RPM 桶。

审慎处理消费上限 429 — 消费上限响应（429, spend_cap_exceeded）意味着周或月的积分预算已耗尽。与 RPM 的 429 不同，它不会在几秒内自动清除——在套用通用重试逻辑前请先检查错误的 type 字段，然后等到上限窗口重置或充值。

预期全局容量限制 — 在高峰期，即使个人限制未触达，也可能遇到全局容量的 429。这些是暂时的——几秒后重试即可。

不要扇出重试 — 当多个 worker 共享一个 API Key 时，避免所有 worker 同时重试。使用协调器或为重试间隔添加随机抖动。