核心指南
请求速率限制
查看每分钟请求数上限,正确处理 429 响应
账户层级决定每分钟可以发送多少次 API 请求。达到上限后,API 会返回 429 rate_limit_exceeded,并通过 Retry-After 告诉客户端需要等待多久。
下表是标准等级限额,当前配置可能调整这些数值。需鉴权请求的这些限额按 API Key 执行。GET /v1/models 等公开发现接口另有独立限额。收到 429 时,以返回的 X-RateLimit-Limit 和 Retry-After 为准,不要把复制的表格当作当前实际限额。
账户限额
| 层级 | 每分钟请求数 |
|---|---|
| User | 1,000 |
| Partner | 10,000 |
| VIP | 10,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 限制和账户速率限制是三件不同的事。