当你的组织每分钟发送的请求或令牌超过其限制允许的数量时,OpenAI API 返回429并附带“已达到速率限制”。 限制适用于组织,不适用于每个用户。 这些错误是暂时性的。 如果等待并再次发送请求,通常会成功。 OpenAI 的另一些 429 错误与计费有关,等待时这些错误不会消失。 有关详细信息,请参阅错误代码。
OpenAI 的速率限制错误如下所示
| Status | Error | 含义 | 重试? |
|---|---|---|---|
429 |
rate_limit_exceeded、每分钟请求数(RPM) |
一分钟内发送的请求过多。 | 是,之后 Retry-After |
429 |
rate_limit_exceeded,每分钟令牌数 (TPM) |
你的请求在一分钟内使用了过多的令牌。 该消息显示你的限制、你使用了多少令牌,以及请求要求多少令牌。 | 是的,在 Retry-After 之后。 更小的请求会有帮助。 |
429 |
slow_down (类型 rate_limit_error) |
你的流量增长过快,即使你在 RPM 和 TPM 限制之内。 | 可以,但速率要更低 |
503 |
server_is_overloaded (类型 service_unavailable_error) |
OpenAI 的服务器正忙。 | 是的,而且每次延迟时间都会更长 |
429 |
credit_balance_exhausted、支出限制或使用限制错误(类型insufficient_quota) |
你的额度不足或超出限制。 | No. 请参阅 OpenAI insufficient_quota和credit_balance_exhausted。 |
其中大多数错误都具有相同的 429 状态,因此仅凭状态无法区分它们。 读取响应体中的error.code。
如何处理 OpenAI 速率限制错误
- 首先检查
error.code。 如果是像credit_balance_exhausted这样的计费错误代码,请停止重试并告知用户。 重试计费错误不会恢复访问。 - 存在
Retry-After时遵循它。 如果缺少,请使用带抖动的指数退避,并限制重试次数。 - 在
slow_down后放慢速度。 降低请求速率,然后逐步增加请求速率。 OpenAI 在 1M 输入 TPM 以上的经验法则是每 15 分钟增加不超过 50% 流量。 - TPM 错误后,发送更少的令牌。 更短的提示和响应让每分钟能容纳更多请求。
- 发生
503后进一步退避。 增加重试之间的延迟,并检查 OpenAI 状态页。 - 告知用户发生的情况。 “系统正忙,将在 5 秒后重试”比永远不会结束的加载动画更好。
OpenAI Python SDK 默认对连接错误和408、409、429、5xx响应重试 2 次,使用短暂的指数退避。 您可以使用 max_retries 进行更改。 当重试次数用完时,SDK 对429引发RateLimitError,对503引发InternalServerError,因此你的代码仍需要相应的处理方案:
import openai
from openai import OpenAI
client = OpenAI(max_retries=3)
BILLING_CODES = {
"credit_balance_exhausted",
"organization_spend_limit_exceeded",
"project_spend_limit_exceeded",
"organization_usage_limit_exceeded",
}
def summarize(text: str) -> str | None:
try:
response = client.responses.create(model="gpt-4.1", input=text)
return response.output_text
except openai.RateLimitError as error:
if error.code in BILLING_CODES:
raise # Retrying won't help: alert and tell the user
return None # Still throttled after retries: show "busy, try again"
except openai.InternalServerError:
return None
如何测试应用处理 OpenAI 速率限制
开发时很少达到 OpenAI 速率限制。 你是唯一的用户,你的提示词很简短。 因此,测试速率限制处理的方式决定了你是否在用户之前发现了 bug。
| Approach | 你找到的内容 | 您错过的内容 |
|---|---|---|
| 等到投入生产 | 真实故障 | 所有情况,直到用户遇到它 |
| 在测试中模拟 API,或让编码代理编写模拟代码 | 重试分支是否运行 | OpenAI 的实际错误正文和代码,以及 SDK 的重试策略。 你的应用还需要一个仅限测试的开关才能访问 mock。 |
| 调用真正的 API,直到它对你进行限流 | 实际行为 | 你无法按需触发特定错误,而且每个请求都消耗令牌 |
| 截获应用的实际流量并按需返回 OpenAI 错误 | 实际 URL、你自己的 SDK 和重试策略,以及 OpenAI 自己的错误格式 | 你的应用无需做任何更改,因此它不会对你的代码进行隔离测试。 这件事留给单元测试来处理。 |
在应用中试用
Dev Proxy拦截你的应用发往api.openai.com的请求并返回 OpenAI 错误,而你的应用继续调用真实 URL。
openai-throttling预设以 OpenAI 自己的格式,从 TPM 和 RPM rate_limit_exceeded、slow_down、credit_balance_exhausted和503server_is_overloaded错误中随机选择,使大多数请求失败。 速率 429 限制响应和 503 响应包括 Retry-After 标头,如果应用在该时间结束前重试,Dev Proxy 会将其报告出来。
下载预设,并使用它启动 Dev Proxy:
devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"
然后像往常一样运行应用并观察其运行情况。 若要安装 Dev Proxy,请参阅 “设置 Dev Proxy”。
若要根据请求使用的提示和补全令牌,测试应用在每分钟令牌耗尽时的行为,请参阅 测试语言模型令牌限制。