OpenAI API 速率限制
速率限制约束客户端在指定时间内访问API的次数或用量。本页解释限流机制、自动层级提升,以及常见错误的缓解方式。
为什么需要速率限制?
限制恶意请求洪泛和滥用,避免服务过载;防止单个组织占用过多资源,维持公平访问;管理整体基础设施负载,使多数用户获得稳定体验。
速率限制如何工作?
指标包括RPM(每分钟请求)、RPD(每天请求)、TPM(每分钟词元)、TPD(每天词元)、IPM(每分钟图像),某些流式音频模型还有每分钟音频分钟数。任一先达到就触发;例如RPM为20、TPM为150k时,即使20次请求各仅100词元,也已达到RPM。
Batch队列按某模型已排队输入词元计量,完成后释放队列占用。其他要点:
- 限制在组织及项目层面,而非单用户;不同模型不同。
- GPT-5.5等长上下文模型的长请求有独立限制,见Limits。
- OpenAI批准的组织月度使用上限,与自行配置的支出限制独立。
- 某些模型共享配额,例如列表中的共享TPM为3.5M,则该组所有模型调用合计占用此量。
- 向量库摄入按向量库ID限流,
/vector_stores/{vector_store_id}/files与/vector_stores/{vector_store_id}/file_batches共享每库300 RPM;大量摄入优先用file_batches。
用量层级
用量层级说明速率限制。组织、项目和 API 密钥是否有权访问模型,请另行检查。
付费层级Build、Launch、Grow随组织累计购买额度达到阈值自动提升,通常获得更高速率。来源快照如下,实际以账户为准:
| 层级 | 资格 | 月度使用上限 |
|---|---|---|
| Free | 位于支持地区 | 100美元 |
| Build | 累计购买5美元额度 | 500美元 |
| Launch | 累计购买100美元额度 | 5,000美元 |
| Grow | 累计购买500美元额度 | 200,000美元 |
Standard速率限制
在Settings → Organization → Limits的Rate limits查看;Usage Tiers下Upgrade tier可升级。它们与Ultrafast限额不同。
| 层级 | 模型系列 | RPM | TPM |
|---|---|---|---|
| Build | Astra、Sol、Terra | 5,000 | 1,000,000 |
| Build | Luna | 5,000 | 2,000,000 |
| Launch | Astra、Sol、Terra | 10,000 | 4,000,000 |
| Launch | Luna | 10,000 | 10,000,000 |
| Grow | Astra、Sol、Terra | 15,000 | 40,000,000 |
| Grow | Luna | 30,000 | 180,000,000 |
支出限制
支出提醒达到金额只通知、不停止流量;硬上限达到后适用请求返回429。它们用于控制组织或项目月度支出,与上述批准使用上限分开。
响应头中的限额
除了账户页,HTTP响应头也可提供剩余请求、词元和重置时间:
| 字段 | 示例值 | 说明 |
|---|---|---|
| Retry-After | 56 | 临时限流时重试前至少等待的秒数(若存在)。 |
| x-ratelimit-limit-requests | 60 | 请求数上限。 |
| x-ratelimit-limit-tokens | 150000 | 词元上限。 |
| x-ratelimit-remaining-requests | 59 | 剩余请求数。 |
| x-ratelimit-remaining-tokens | 149984 | 剩余词元。 |
| x-ratelimit-reset-requests | 1s | 请求额度重置前时间。 |
| x-ratelimit-reset-tokens | 6m0s | 词元额度重置前时间。 |
| x-ratelimit-limit-project-tokens | 60000 | 项目词元上限。 |
| x-ratelimit-remaining-project-tokens | 57000 | 项目剩余词元。 |
| x-ratelimit-reset-project-tokens | 3s | 项目词元额度重置时间。 |
项目头可能只在项目词元限制适用时出现。临时429和模型过载503可能有Retry-After,但它不意味着账单、配额等需要人工处理的错误能靠重试解决。
微调速率限制
可在面板查看,或通过API获取:
来源示例 1(bash):
## [中文] 查询组织微调速率限制,需要相应权限。
curl https://api.openai.com/v1/fine_tuning/model_limits \
-H "Authorization: Bearer $OPENAI_API_KEY"
模型可用性
用量层级和模型访问权限分别管理。如果 Playground 或 GET /v1/models 未显示模型,或请求返回 model_not_found,按以下步骤检查。
- 核对模型目录中的模型 ID、支持的端点,以及停用或可用性公告。
- 在 Playground 选择对应组织和项目。使用失败请求的 API 密钥,以及相同的
OpenAI-Organization和OpenAI-Project请求头列出模型,比较两边结果。 - 请项目管理员检查模型权限和数据保留设置,并确认模型特定的访问要求及分批开放公告。
- 调整设置后刷新模型列表或 Playground。如果仍不可用,向支持团队提供模型 ID、组织和项目 ID、请求时间、错误信息,以及可用的
x-request-id。请保管好 API 密钥。
缓解错误
应对流量骤增与模型过载
| 状态 | 类型 | 代码 | 含义与措施 |
|---|---|---|---|
| 429 | rate_limit_error | slow_down | 增长过快;遵守Retry-After,降低流量后逐渐增加。 |
| 503 | service_unavailable_error | server_is_overloaded | 模型暂时过载;遵守Retry-After后重试,持续发生则增加等待。 |
没有响应头时采用增加间隔并带随机抖动的重试。slow_down即使未超过RPM/TPM也可能发生,它限制增长速度。经验规则是达到100万输入TPM后,每15分钟增长不超过50%,触发点仍随模型与流量变化。
经常触发的Enterprise按量客户可考虑Scale Tier;GPT-5.6及以后见Reserved Tier。容量方案不能替代正确等待与渐进爬升。
更新已有错误处理器
某些旧端点原来对两类情况都返回503 slow_down;现在骤增为429 slow_down,过载为503 server_is_overloaded。视频任务创建前拒绝原先可能是429 invalid_request_error/rate_limit_exceeded,现在分别采用上述429和503;视频作业状态内错误是另一情况。
SDK同时处理429与503,并检查error.code。Python、TypeScript、Ruby分别用RateLimitError和InternalServerError;Java用RateLimitException和InternalServerException。仍可能收到旧响应时需保留兼容。其他错误也可使用相同状态码,先看正文再决定恢复。
流式请求开始前适用这些HTTP错误;开始后错误可能作为流事件到达。已经消费输出时,不能自动重放整次请求。
还可以采取哪些措施?
参考Cookbook及并行请求脚本。对编程访问、批量功能、自动社交发布应谨慎,只向可信客户开放;给单个用户设置日/周/月用量限制,超额可硬封顶或人工复核,防止自动化滥用。
指数退避重试
有效Retry-After是最短等待时间,可再加少量随机延迟,避免同时重试。官方SDK会按配置重试合格429/503,但对长等待的支持因版本不同;超过支持或配置的最大等待时,应停止重试并延后任务,不能提前重试。SDK拒绝过长等待时可能返回原HTTP错误。
取消与超时需单独处理:取消请求或总截止时间到达可能终止重试而不返回原HTTP错误;每次尝试的超时不一定是整个操作的截止时间。
自有HTTP客户端应先遵守有效Retry-After;缺失/无效再退回带抖动的指数退避。同时限制尝试次数及总耗时,关闭SDK重试或把它计入预算,避免嵌套放大。不重试账单、配额等需要先采取行动的错误。
指数退避让首次失败后短暂等待,连续失败则逐步增长,直到成功或达到上限。优点是自动恢复、首次尝试较快、持续失败降低压力,随机抖动减少重试碰撞。失败请求也占每分钟限额,持续立即重发无效。
以下示例使用 Responses API 向 gpt-6-luna 发送请求。每个重试封装都限制尝试次数,并关闭 SDK 内置重试。
这些Python包装器没有读取Retry-After,使用前须补充有效服务端等待提示处理,并关闭或统计SDK重试。本地未运行旧模型。
示例1:Tenacity库
Tenacity是Apache 2.0许可的通用Python重试库。用tenacity.retry装饰器及wait_random_exponential增加随机指数退避:
来源示例 2(python):
## [中文] 对 Responses 请求执行有限次数的退避重试。SDK 内置重试已关闭。
from openai import OpenAI, RateLimitError
from tenacity import (
retry,
retry_if_exception_type,
stop_after_attempt,
wait_random_exponential,
) # for exponential backoff
client = OpenAI(max_retries=0)
@retry(
retry=retry_if_exception_type(RateLimitError),
wait=wait_random_exponential(min=1, max=60),
stop=stop_after_attempt(6),
reraise=True,
)
def response_with_backoff(**kwargs):
return client.responses.create(**kwargs)
response = response_with_backoff(
model="gpt-6-luna",
input="Say hello in one sentence.",
reasoning={"effort": "none"},
max_output_tokens=64,
)
print(response.output_text)
它是第三方工具,OpenAI不保证其可靠性或安全性。
示例2:backoff库
backoff也提供退避重试装饰器:
来源示例 3(python):
## [中文] 对 Responses 请求执行有限次数的退避重试。SDK 内置重试已关闭。
import backoff
import openai
from openai import OpenAI
client = OpenAI(max_retries=0)
@backoff.on_exception(backoff.expo, openai.RateLimitError, max_tries=6)
def response_with_backoff(**kwargs):
return client.responses.create(**kwargs)
response = response_with_backoff(
model="gpt-6-luna",
input="Say hello in one sentence.",
reasoning={"effort": "none"},
max_output_tokens=64,
)
print(response.output_text)
同样属于第三方,OpenAI不提供可靠性或安全保证。
示例3:手动实现退避
不使用第三方库时可从以下实现开始。来源不保证该方案安全性或效率,需按应用完善。
来源示例 4(python):
## [中文] 对 Responses 请求执行有限次数的退避重试。SDK 内置重试已关闭。
## imports
import random
import time
import openai
from openai import OpenAI
client = OpenAI(max_retries=0)
## define a retry decorator
def retry_with_exponential_backoff(
func,
initial_delay: float = 1,
exponential_base: float = 2,
jitter: bool = True,
max_retries: int = 10,
errors: tuple = (openai.RateLimitError,),
):
"""Retry a function with exponential backoff."""
def wrapper(*args, **kwargs):
# Initialize variables
num_retries = 0
delay = initial_delay
# Loop until a successful response or max_retries is hit or an exception is raised
while True:
try:
return func(*args, **kwargs)
# Retry on specific errors
except errors:
# Increment retries
num_retries += 1
# Check if max retries has been reached
if num_retries > max_retries:
raise Exception(
f"Maximum number of retries ({max_retries}) exceeded."
)
# Increment the delay
delay *= exponential_base * (1 + jitter * random.random())
# Sleep for the delay
time.sleep(delay)
# Raise exceptions for any errors not specified
except Exception:
raise
return wrapper
@retry_with_exponential_backoff
def response_with_backoff(**kwargs):
return client.responses.create(**kwargs)
response = response_with_backoff(
model="gpt-6-luna",
input="Say hello in one sentence.",
reasoning={"effort": "none"},
max_output_tokens=64,
)
print(response.output_text)
让max_tokens接近预期回复长度
来源说明限额估算取max_tokens与按请求字符量估计词元数的较大值,因此应让生成上限接近期望输出。具体参数名仍需遵循所选端点和模型,不要直接把旧参数套入新接口。
合并请求
无需即时响应时使用异步Batch API,不消耗同步速率池。需要同步时,若RPM已满而TPM仍有空间,可在单次请求内合并多个任务,提高吞吐,尤其适合较小模型。
来源还介绍旧Completions的prompt字符串数组方式;这是相应端点的用法,与Batch API文件作业不同,不能推定所有现代接口都接收该参数。