中文 ▾
获取 API 密钥

LLM API 429 错误:原因与解决方法

LLM API 错误 429 表示服务器暂时拒绝请求,并非永久拒绝。在此 API 中,有三种不同的原因,每种原因需要不同的解决方法。

更新于

八车道关卡前排队的光子包,说明 API 速率限制

要点

三种 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 个槽位。

简短的调试检查清单

  1. 记录每个 429 的完整错误正文和 X-Request-Id 头。code 字段将 rate_limited 与 concurrency 分开。
  2. 检查你的密钥是否为试用密钥。如果是,预计允许 2 个并发请求和每分钟 60 个请求。
  3. 计算使用密钥的每个程序,而不仅仅是失败的那个。
  4. 查找未关闭的流,以及没有延迟立即重试的循环。立即重试循环会将一个 429 变成一百个。
  5. 通过 X-Balance-USD 或 GET /v1/balance 确认余额。余额为空是与 429 不同的问题,但检查只需几秒钟。

失败的请求不会收费,因此重试不会因被拒绝的尝试而花费您的 token。有关状态代码和头部的完整列表,请参阅 文档。如果您需要比试用密钥更高的限制,获取 API 密钥 并充值。

问答

429 错误是我的责任还是服务商的责任?

两者皆有可能。rate_limited 和 concurrency 代码表示你的密钥超出了限制。带有 Retry-After 头的 429 也可能来自临时过载,等待指定时间后重试是正确的做法。

我应该等多久再重试?

如果响应包含 Retry-After 头,请至少等待该秒数。否则从一秒开始,每次加倍延迟,并加入少量随机抖动。

被拒绝的请求会花钱吗?

不会。失败或被拒绝的请求不收费。

我可以提高限制吗?

完整密钥允许 8 个并发请求和每分钟 300 个请求,而试用密钥仅为 2 个并发请求和每分钟 60 个请求。超出限制后,请在您的侧通过队列分散工作。

填写一张表单即可获得密钥

创建账户,复制密钥,更改基础 URL。这就是全部设置。