429 表示你的流量超过了某个速率限制:每分钟请求数、同时请求数、每分钟 token 数或支出。解决它分两部分。好好重试:有上限的指数退避加随机抖动,并遵守 Retry-After。一次少发一点:用信号量把同时请求数限制在密钥的上限,再加一个队列。下文都附有代码。
完整的状态码参考请看错误与重试指南;需要检查点和超时设置、运行数小时的智能体,请看长时间运行的智能体:超时与重试。
429 和 5xx 有什么区别?
| 状态码 | 谁的问题 | 重试? | 怎么做 |
|---|---|---|---|
| 429 | 你的流量超过了限制 | 是 | 带抖动的退避;遵守 Retry-After;降低并发 |
| 500 / 502 / 503 / 504 | 服务器端 | 是 | 有上限的指数退避 |
| 连接重置、超时 | 网络或服务器 | 通常是 | 退避;对于流式输出,仅在可以接受重新计费时 |
| 400 / 422 | 请求有误 | 否 | 修正请求体 |
| 401 / 402 / 403 | 密钥、余额或策略 | 否 | 修正密钥、给账户充值、修正白名单 |
| 413 | 请求过大 | 否 | 缩小请求 |
在 BroadNet Inference 上,429 可能对应四种限制中的任何一种:速率、并发、token 速率或支出。支出限制不会在 30 秒内解除。BroadNet 的文档没有说明错误响应体的哪个字段会指出具体限制,所以请把响应体记录下来,并与密钥详情中显示的限制对照。
我们的开放数据集大模型 API 免费额度与速率限制比较了 14 家服务商在免费使用、起始速率限制、是否需要绑卡以及是否用免费额度数据训练等方面公布的信息,每个数值都附有来源和日期。
哪些限制会导致 429?
先弄清你面对的具体数字。在 BroadNet Inference 上:
| 密钥类型 | 每分钟请求数 | 同时请求数 | 其他 |
|---|---|---|---|
| 按量付费 | 30 | 4 | 共享支出预算 |
| 按小时密钥 | 120 | 1 路流 | 每分钟 300,000 token |
| 不限量套餐会话 | — | 每个会话 1 个请求 | 无 token 计量 |
对大模型来说,同时请求数最关键。流式回答会一直占用名额,直到最后一个 token 到达,所以回答越长,占用时间就越长,等于模型生成它所需的时间(BroadNet 给出的典型速度是 约每秒 100 个 token)。并行调用数一旦超过密钥的 4 个名额,多出来的调用就会收到 429,尽管你那一分钟只发了寥寥几个请求。这是并发问题,单靠退避处理得并不好。要在上线前根据限制规划 worker 数量,可以用免费的大模型速率限制计算器。对于由大量条目组成的固定任务,大模型批处理任务规划器能把同样的限制换算成运行时间。其他服务商的计算方式不同(每分钟 token 数、每天请求数或同时请求数);各服务商的大模型 API 速率限制根据 13 家服务商自己的文档做了比较。
怎么写带抖动的退避?
普通的指数退避依次等待 1、2、4、8 秒。如果一百个 worker 在同一时刻被限流,它们也会在同一时刻回来。AWS 对 100 个相互竞争的客户端做的模拟发现,全抖动让调用次数减少了一半以上,并且比不加抖动的退避更快完成。最简单的版本是全抖动:在零和指数上限之间随机等待:
import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
for attempt in range(max_attempts):
try:
return client.chat.completions.create(**kwargs)
except (RateLimitError, APIStatusError, APIConnectionError) as e:
status = getattr(e, "status_code", None)
if status is not None and status not in RETRYABLE:
raise # 400, 401, 403...: retrying will not help
if attempt == max_attempts - 1:
raise
retry_after = None
if getattr(e, "response", None) is not None:
retry_after = e.response.headers.get("retry-after")
wait = random.uniform(0, min(cap, base * 2 ** attempt))
if retry_after and retry_after.isdigit():
wait = max(wait, float(retry_after))
time.sleep(wait)
max_retries=0 关闭了 SDK 自带的重试,避免重复重试。如果你满意 SDK 的内置行为,也可以反过来:不写自己的循环,在客户端上设置 max_retries=4,就像 Python SDK 指南里那样。官方 Python 和 Node SDK 默认对连接错误、408、409、429 和 5xx 重试两次。
Retry-After 是一个标准响应头(RFC 9110),值可以是秒数或日期。BroadNet 的文档并未承诺一定会发送它,所以代码把它当作可选项处理。
怎样在 429 发生之前就阻止它?
把同时进行的请求数限制在密钥的上限。在 Python 中,asyncio.Semaphore 只需一个对象加一个 async with 块就能搞定。代码以 4 为例;请把它设为你的密钥的同时请求上限(BroadNet 按量付费密钥为 4):
import asyncio, os
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4) # match the key's in-flight limit
async def ask(prompt):
async with slots:
r = await client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main(prompts):
return await asyncio.gather(*(ask(p) for p in prompts))
results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))
gather 会启动所有任务,但同时运行的数量不会超过信号量允许的数量,其余的在信号量的队列中等待。在 Node 中,p-limit 包可以做同样的事,同样以 4 为示例值:
// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";
const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit
async function ask(prompt) {
const r = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: prompt }],
});
return r.choices[0].message.content;
}
const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));
如果还要满足每分钟上限,再加一个令牌桶,每 60 / rpm 秒放出一个许可,其中 rpm 是你的密钥每分钟的请求数上限(BroadNet 按量付费密钥为 30)。
什么时候需要真正的队列?
信号量只存在于一个进程里。一旦多个 worker 或服务器共用一个密钥,限制是共享的,而每个进程只能看到自己的流量。这时:
- 把任务放进共享队列(Redis、SQS、数据库表)。
- 运行固定数量的消费者,数量等于密钥的同时请求上限。
- 给每个任务一个 ID,并按 ID 存储结果,这样重试的任务不会执行两次。
- 交互流量和批处理流量走不同的密钥或不同的队列,这样批处理积压永远不会挡住正在等待回复的用户。
对于数千个条目、又没有 Batch API 的批量任务,请看可续跑的批处理执行器。
哪些重试错误会把 429 变成故障?
- **无上限的重试。**在长时间故障期间,没有上限的重试循环会成倍放大你的负载,在按 token 计费时还会放大你的账单。
- **盲目重试只完成了一半的流。**如果流已经返回了一些 token,重试就是一次全新的推理,用户可能会看到重复的文字。如何检测不完整的流,请看流式输出一文。
- **重试账户错误。**按量付费额度用完时的 401,或余额不足时的 402,不会自己好起来。
记录每一次重试的状态码、等待时间和响应头 X-Request-ID,BroadNet 的文档要求你保留它以便联系支持。重试率上升,是你需要更多容量的最早信号;用量日志介绍了如何记录它。
BroadNet Inference 适合什么场景
BroadNet 的限制是公开的,而且小到足以据此做设计:按量付费密钥同时 4 个请求。这适合应用和智能体,但对于想在一个密钥上同时发起数百个调用的批量任务来说太紧了。对于智能体,不限量套餐没有 token 计量,每个会话同一时间运行一个请求;需要并行时就增加会话,详见并行运行编程智能体。当前限制请看 API 参考。
