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 指南演示了如何读取这个响应头。
