BroadRouter

大模型 API 报 429 错误怎么办:退避、抖动与并发限制

BroadNet Inference 团队 · 阅读约 5 分钟 · 发布于 · 更新于

429 表示你触发了速率、并发或支出限制。用有上限的指数退避加随机抖动来重试,服务器发送 Retry-After 时遵守它。然后从源头预防大部分 429:用信号量把同时进行的请求数限制在密钥的上限,其余排队。5xx 用同样的方式重试;其他 4xx 错误则应修正,而不是重试。

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 或服务器共用一个密钥,限制是共享的,而每个进程只能看到自己的流量。这时:

  1. 把任务放进共享队列(Redis、SQS、数据库表)。
  2. 运行固定数量的消费者,数量等于密钥的同时请求上限。
  3. 给每个任务一个 ID,并按 ID 存储结果,这样重试的任务不会执行两次。
  4. 交互流量和批处理流量走不同的密钥或不同的队列,这样批处理积压永远不会挡住正在等待回复的用户。

对于数千个条目、又没有 Batch API 的批量任务,请看可续跑的批处理执行器。

哪些重试错误会把 429 变成故障?

  • **无上限的重试。**在长时间故障期间,没有上限的重试循环会成倍放大你的负载,在按 token 计费时还会放大你的账单。
  • **盲目重试只完成了一半的流。**如果流已经返回了一些 token,重试就是一次全新的推理,用户可能会看到重复的文字。如何检测不完整的流,请看流式输出一文。
  • **重试账户错误。**按量付费额度用完时的 401,或余额不足时的 402,不会自己好起来。

记录每一次重试的状态码、等待时间和响应头 X-Request-ID,BroadNet 的文档要求你保留它以便联系支持。重试率上升,是你需要更多容量的最早信号;用量日志介绍了如何记录它。

BroadNet Inference 适合什么场景

BroadNet 的限制是公开的,而且小到足以据此做设计:按量付费密钥同时 4 个请求。这适合应用和智能体,但对于想在一个密钥上同时发起数百个调用的批量任务来说太紧了。对于智能体,不限量套餐没有 token 计量,每个会话同一时间运行一个请求;需要并行时就增加会话,详见并行运行编程智能体。当前限制请看 API 参考。

常见问题

大模型 API 返回 HTTP 429 是什么意思?

Too Many Requests(请求过多)。你超过了每分钟请求数、同时请求数、每分钟 token 数或支出的某项限制。该请求没有被处理,所以等待一段时间后重新发送是安全的。

遇到 429,应该等多久再重试?

如果服务器发送了 Retry-After,就按它来。否则从 1 秒左右开始,每次翻倍,上限设在 30 到 60 秒左右,在零和该上限之间随机选择等待时间。尝试四到六次后停止。

大模型 API 的 500 和 503 错误要重试吗?

要,用同样有上限的退避。它们是服务器端的问题。400、401、403 或 422 每次都会以同样的方式失败,所以应该修正它们。

OpenAI SDK 会自动重试 429 吗?

会。官方 Python 和 Node SDK 默认对连接错误、408、409、429 和 5xx 重试两次,使用较短的指数退避。批处理任务可以调大 max_retries,并加上你自己的并发限制。

每分钟请求数没超,为什么还是报 429?

通常是并发限制。较长的流式响应会占用好几秒甚至更久,所以几个并行调用就可能撞上同时请求上限,而每分钟请求数看起来并不高。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity