BroadRouter
开始使用

BroadNet Inference 错误码,以及什么时候该重试

更新于

先检查 HTTP 状态码,再解析响应体。429 和 5xx 用有上限的指数退避重试。400、403、413 和 422 要先修正请求再重试。401 检查密钥和余额,402 给账户充值。始终记录 X-Request-ID 响应头,供技术支持排查。

API 会返回普通的 HTTP 状态码和机器可读的错误码。根据状态码决定下一步怎么做。下表依据 BroadNet 的 API 参考文档整理。

状态码 含义 怎么处理
400 / 422 请求或字段无效 先修正请求
401 密钥缺失、无效或已过期,按量付费预算被冻结,或额度已用完 检查密钥状态和账户余额
402 insufficient_balance 账户余额不足以支付一笔购买;响应体中包含余额和价格 给账户充值后再试
403 被模型、路由或 IP 策略拒绝 解决不匹配的问题,例如 IP 白名单
409 与账户状态冲突:mint_in_progress、key_limit_reached、credential_limit_reached、key_pending 只重试 mint_in_progress,并使用同一个 request_id
413 请求过大;转写文件上限为 26,214,400 字节 缩小请求
429 达到速率、并发、token 速率或消费限额 阅读响应中的详细信息,退避后重试
500 / 502 / 503 / 504 服务器端处理出错 用有上限的指数退避重试;购买按小时密钥时复用同一个 request_id

BroadNet 的文档要求先检查 HTTP 状态码,再解析 JSON 响应体,然后在有错误码时读取机器可读的 error 字段。

哪些限制会触发 429?

按量付费密钥每分钟允许 30 个请求,同时最多 4 个进行中的请求。根据 BroadNet 的文档,按小时密钥每分钟 120 个请求、一路流、每分钟 300,000 个 token。在不限量套餐上,每个会话同一时间只处理一个请求。想了解这些限制与 OpenAI、Anthropic、Groq 和 DeepSeek 相比如何,请阅读各服务商的大模型 API 速率限制。

用 OpenAI SDK 怎么重试?

根据 GitHub 上的 README,OpenAI Python SDK 默认就会对连接错误、408、409、429 和 5xx 响应重试两次,并使用短时间的指数退避。它的默认超时是 10 分钟。建议把这两项都显式设置:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
    max_retries=4,   # 0 turns automatic retries off
    timeout=120,     # seconds; raise it for long reasoning answers
)

代码注释的意思是:max_retries=0 关闭自动重试;timeout 以秒为单位,回答需要长时间思考时请调高。

怎么自己实现退避?

如果不通过 SDK 调用 API,请同时限制重试次数和等待时间:

import random, time, requests

RETRY = {429, 500, 502, 503, 504}

def post_with_backoff(url, headers, body, tries=5):
    for attempt in range(tries):
        r = requests.post(url, headers=headers, json=body, timeout=120)
        if r.status_code not in RETRY:
            return r                      # success, or an error to fix rather than retry
        time.sleep(min(30, 2 ** attempt) + random.random())
    return r

状态码不在重试列表里时直接返回:要么成功,要么是应该修正而不是重试的错误。不要原样重试 400、403、413 或 422:同一个请求会以同样的方式失败。对话请求的每一次重试都是一次新的推理,在按量付费下会再次计费。通用做法见指数退避。

安全地重试按小时密钥的购买

POST /portal/keys/hourly 接受一个 request_id。遇到超时、连接中断、409 mint_in_progress 或 5xx 后,请用同一个 request_id 重试。重复使用的 request_id 绝不会创建第二个密钥或再次扣费;重放请求会返回 already_issued: true 和密钥别名。在确认第一次的结果之前,不要生成新的 id。更多内容见幂等键。

故障排查

  • 刚充值完就返回 401。 BroadNet 的账户页面显示最近记录的额度,资金变更在生效过程中会标记为更新中。刷新页面,等更新完成后再试。
  • 每分钟只有几个请求也返回 429。 你很可能撞上了 4 个请求的并发限制,比如有多个长时间的流在并行运行。请使用一个小型的工作池。
  • 一个模型返回 403,另一个不会。 密钥的策略不覆盖那个模型或路由。例如,套餐密钥只用于 broadnet/deepseek-v4.1-flash,按小时密钥只覆盖 broadnet/gemma-4-26b-a4b。
  • SDK 重试后被扣了两次费。 重试的对话请求是一次新的推理。如果重复回答的成本高于一次失败,请设置 max_retries=0。

联系技术支持时要提供什么

请提供 X-Request-ID 响应头的值、UTC 时间戳、路由、HTTP 状态码和你的密钥别名。绝对不要发送密钥本身。OpenAI Python SDK 指南演示了如何读取这个响应头。

常见问题

大模型 API 返回 429 错误时应该重试吗?

应该,使用有上限的指数退避。在 BroadNet Inference 上,429 表示达到了速率、并发、token 速率或消费限额中的某一项。如果反复出现,请降低并行度;如果原因是消费限额,就停止重试。

密钥明明是对的,为什么还返回 401?

在 BroadNet 上,401 不只表示密钥错误或过期,也包括按量付费额度用完或预算被冻结。请在账户页面检查余额和密钥状态。

这里的 401 和 403 有什么区别?

401 与密钥或账户额度有关。403 表示密钥本身有效,但请求被模型、路由或 IP 策略拒绝,例如从不在白名单上的地址发起调用。

OpenAI SDK 会自动重试出错的请求吗?

会。OpenAI Python SDK 默认会对连接错误、408、409、429 和 5xx 重试两次,并使用短时间的指数退避。设置 max_retries 可以修改次数,设为 0 则关闭重试。

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