三种 429 错误
HTTP 429 是标准的“请求过多”状态。这里涵盖三种情况,JSON 错误响应体告诉你具体是哪一种。
| 错误代码 | 含义 | 典型修复方法 |
|---|---|---|
rate_limited | 每分钟请求过多 | 放慢速度,在一分钟内分散请求 |
concurrency | 同时运行的请求过多 | 降低并发性,等待槽位释放 |
过载,带有 Retry-After: 5 | 服务临时负载,非你所能控制 | 等待头中指定的秒数,然后重试 |
先阅读代码,因为针对一种原因的修复对另一种原因无效。如果你的实际问题是有 20 个工作者同时发起请求,将每分钟请求量减半并无帮助。
了解你的限制
限制取决于密钥类型:
- 完整密钥: 8 个并发请求和每分钟 300 个请求。
- 试用密钥: 2 个并发请求和每分钟 60 个请求。
每条响应都包含 X-RateLimit-Limit-Requests 和 X-RateLimit-Limit-Concurrency,因此你的客户端可以读取上限,而无需硬编码。试用密钥是新用户常见的出错原因:一个每次只运行 1 个请求的脚本,当你添加 4 个线程池时就会开始失败。试用密钥用于测试,任何 ≥$20 的充值即可获取完整密钥(金额和赠送额度见 定价页面)。
上述数字是按密钥计算的。如果一个密钥被 Web 应用、cron 作业和队友的笔记本共享,它们都从同一个池中消耗,在将三个工作负载相加之前,429s 看起来是随机的。
为什么流式输出更容易导致并发错误
普通请求会占用并发槽位一秒钟或两秒钟。流式请求(stream: true)会一直占用,直到最后一个 token 到达且流关闭。长回答可能会让一个槽位占用数十秒,因此在有多个活跃用户的聊天应用中,8 个槽位会很快用完。
这里的大多数问题由两个错误引起。第一个是放弃流而不关闭它:如果客户端停止读取但保持连接打开,槽位将保持占用,直到连接结束。始终在 finally 块中关闭响应,或使用 SDK 的上下文管理器。第二个是在第一个流仍处于活动状态时打开第二个流来重试,这会在槽位不足时恰好使槽位使用量翻倍。
如果你的应用需要比密钥允许的更多的同时长流,请在本地对新聊天进行排队,并显示短暂的等待状态。这比让用户看到原始错误要好。
带退避的 Python 重试代码
模式很简单:捕获 429,读取代码,等待,以逐渐增加延迟和一些随机性重试,并在几次尝试后放弃。此版本使用官方 openai 包针对服务的 base URL:
import random
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
max_retries=0, # we handle retries ourselves
)
def chat(messages, attempts=5):
for i in range(attempts):
try:
r = client.chat.completions.create(
model="uncensored",
messages=messages,
)
return r.choices[0].message.content
except RateLimitError as e:
headers = e.response.headers
wait = float(headers.get("Retry-After", 0))
if not wait:
wait = min(30, 2 ** i) # 1, 2, 4, 8, 16 seconds
wait += random.uniform(0, 1) # jitter
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(chat([{"role": "user", "content": "Reply with the word ok."}]))
当存在该头时,将其用作最小等待时间。当缺失时,指数延迟对 rate_limited 有效,因为每分钟窗口会移动。抖动可防止许多工人在同一时刻重试。
限制并发调用,让你很少遇到 429
重试处理症状。信号量通过从不发送超过你的槽位数量的请求来防止大部分症状。将其设置得略低于限制,以便重试或意外请求仍有空间:
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6) # full key allows 8; use 1 on a trial key
async def ask(prompt):
async with sem:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main():
prompts = [f"Give one fact about the number {n}." for n in range(50)]
results = await asyncio.gather(*(ask(p) for p in prompts))
print(len(results))
asyncio.run(main())
对于每分钟限制,每分钟 300 个请求平均为每秒 5 个。如果你批量处理数千个短任务,请在信号量前添加少量休眠或令牌桶。由于 SDK 默认也会自行重试,请显式设置 max_retries,使你的逻辑与 SDK 的重试不会叠加并放大等待时间。
使用 curl 复现和检查 429
在更改代码之前,查看原始响应。向 curl 添加 -i 以打印头,并并行发送几个请求以故意引发错误:
for i in 1 2 3 4; do
curl -i -s https://api.onekeyllmapi.com/v1/chat/completions -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait
对于同时允许 2 个请求的试用密钥,第三次和第四次调用应返回状态 429 以及错误代码 concurrency。对于完整密钥,你需要同时发起超过 8 个请求。查看每次回复中的三项内容:状态行、如果有的话的 Retry-After 头,以及 JSON 正文中的 error.code 字段。这个小实验比一小时盲目猜测更有用,如果出现问题,可向支持团队展示可复现的情况。
为此设计,而不是围绕它设计
将 429 视为正常事件,如超时。将模型调用放在一个函数后面,记录每次重试及其原因,并暴露一个计数器,以便你在重试率上升时注意到。上升的重试率是流量超过单个密钥限制的早期迹象,早于用户投诉。对于聊天产品,每个用户的少量内存队列可以防止一个繁忙账户占用其他人的所有 8 个槽位。
简短的调试检查清单
- 记录每个 429 的完整错误正文和
X-Request-Id头。code 字段将rate_limited与concurrency分开。 - 检查你的密钥是否为试用密钥。如果是,预计允许 2 个并发请求和每分钟 60 个请求。
- 计算使用密钥的每个程序,而不仅仅是失败的那个。
- 查找未关闭的流,以及没有延迟立即重试的循环。立即重试循环会将一个 429 变成一百个。
- 通过
X-Balance-USD或GET /v1/balance确认余额。余额为空是与 429 不同的问题,但检查只需几秒钟。
失败的请求不会收费,因此重试不会因被拒绝的尝试而花费您的 token。有关状态代码和头部的完整列表,请参阅 文档。如果您需要比试用密钥更高的限制,获取 API 密钥 并充值。
