核心指南

请求速率限制

查看每分钟请求数上限,正确处理 429 响应

账户层级决定每分钟可以发送多少次 API 请求。达到上限后,API 会返回 429 rate_limit_exceeded,并通过 Retry-After 告诉客户端需要等待多久。

下表是标准等级限额,当前配置可能调整这些数值。需鉴权请求的这些限额按 API Key 执行。GET /v1/models 等公开发现接口另有独立限额。收到 429 时,以返回的 X-RateLimit-Limit 和 Retry-After 为准,不要把复制的表格当作当前实际限额。

账户限额

层级每分钟请求数
User1,000
Partner10,000
VIP10,000

需要调整限额时,请把账户邮箱、预计请求量和使用场景发到 hello@tokenlab.sh。

429 响应

{
  "error": {
    "message": "Rate limit exceeded (1000/min for user role). Please retry later.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

429 响应带有这些响应头:

响应头含义
Retry-After下一次请求前需要等待的秒数
X-RateLimit-Limit这把 API 密钥每分钟允许的请求数
X-RateLimit-Remaining当前窗口内剩余的请求数
X-RateLimit-Reset窗口重置的 Unix 时间(秒)
Retry-After: 8

同一 IP 反复认证失败也会被限流。一分钟内失败约 20 次后,API 返回 429,消息为 Too many failed authentication attempts. Please retry later.,并带 Retry-After。遇到 401 请先修正 API 密钥,不要重试。

按服务端给出的时间重试

有 Retry-After 时直接使用。没有这个响应头时,可以使用带随机抖动的指数退避。重试次数必须有限,避免请求队列一直增长。

import random
import time
from openai import RateLimitError

def chat_with_rate_limit_retry(client, model, messages, attempts=4):
    for attempt in range(attempts):
        try:
            return client.with_options(max_retries=0).chat.completions.create(
                model=model,
                messages=messages,
            )
        except RateLimitError as exc:
            if attempt == attempts - 1:
                raise
            header = exc.response.headers.get("Retry-After")
            wait = float(header) if header else min(30, 2 ** attempt + random.random())
            time.sleep(wait)

避免集中触发限额

  • 应用可能突然产生大量请求时,使用队列削平峰值。
  • 同时限制并发数和每分钟平均请求数。
  • 只有结果适合复用时才缓存。
  • 参数、鉴权、余额和权限错误不能靠重试解决。
  • 按 API 密钥统计重复的 429,避免一个客户端占满整个应用的请求额度。

更快的模型不会提高账户请求上限。模型速度、token 限制和账户速率限制是三件不同的事。

本页内容