---
title: "大模型 API 错误码 401、402、409、429：哪些该重试 | BroadRouter"
description: "BroadNet Inference API 每个 HTTP 状态码的含义：哪些要指数退避重试，哪些要先修正请求，以及联系技术支持时要带上请求 ID 等哪些信息。"
url: https://broadrouter.com/zh/guides/errors-and-retries/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。 [阅读英文原文](https://broadrouter.com/guides/errors-and-retries/) (2026-11-14 更新).

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

更新于 2026-11-14

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

API 会返回普通的 HTTP 状态码和机器可读的错误码。根据状态码决定下一步怎么做。下表依据 BroadNet 的 [API 参考文档](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-errors-and-retries&utm_content=body#errors)整理。

| 状态码 | 含义 | 怎么处理 |
| --- | --- | --- |
| 400 / 422 | 请求或字段无效 | 先修正请求 |
| 401 | 密钥缺失、无效或已过期，按量付费预算被冻结，或额度已用完 | 检查密钥状态和账户余额 |
| 402 `insufficient_balance` | 账户余额不足以支付一笔购买；响应体中包含余额和价格 | 给账户充值后再试 |
| 403 | 被模型、路由或 IP 策略拒绝 | 解决不匹配的问题，例如 [IP 白名单](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/) |
| 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。在[不限量套餐](https://broadrouter.com/zh/guides/unlimited-llm-api-sessions/)上，每个会话同一时间只处理一个请求。想了解这些限制与 OpenAI、Anthropic、Groq 和 DeepSeek 相比如何，请阅读[各服务商的大模型 API 速率限制](https://broadrouter.com/zh/blog/llm-api-rate-limits-by-provider/)。

## 用 OpenAI SDK 怎么重试？

根据 [GitHub 上的 README](https://github.com/openai/openai-python#retries)，OpenAI Python SDK 默认就会对连接错误、408、409、429 和 5xx 响应重试两次，并使用短时间的指数退避。它的默认超时是 10 分钟。建议把这两项都显式设置：

```python
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，请同时限制重试次数和等待时间：

```python
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：同一个请求会以同样的方式失败。对话请求的每一次重试都是一次新的推理，在按量付费下会再次计费。通用做法见[指数退避](https://broadrouter.com/zh/glossary/exponential-backoff/)。

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

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

## 故障排查

-   **刚充值完就返回 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 指南](https://broadrouter.com/zh/guides/openai-python-sdk/)演示了如何读取这个响应头。

## 本指南涉及的术语

[速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/)

速率限制是 API 对客户端在一个时间窗口内的使用量设定的上限，例如每分钟请求数或每分钟 token 数。超出限制的请求会被拒绝，通常返回 HTTP 429 Too Many Requests，直到用量回落到限制以下。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[并发（concurrency）](https://broadrouter.com/zh/glossary/concurrency/)

并发（concurrency）是客户端在同一时刻正在进行中的请求数。大模型 API 往往按密钥或套餐单独限制并发，与每分钟请求数分开计算，因为每个未完成的请求在响应结束前都会占用 GPU 资源。

[预付额度（prepaid credit）](https://broadrouter.com/zh/glossary/prepaid-credit/)

预付额度是在使用前存入 API 账户的资金。每个请求的费用从余额中扣除，余额用完后，计量计费的请求会停止，直到你充值。它把支出上限锁定在你已支付的金额之内。

[指数退避（exponential backoff）](https://broadrouter.com/zh/glossary/exponential-backoff/)

指数退避（exponential backoff）是一种重试策略：客户端每失败一次，就等待更长时间再重试，通常把延迟翻倍，直到达到上限。在每次等待中加入随机抖动（jitter），可以把众多客户端的重试错开，避免它们在同一时刻打到服务器上。

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

[每秒 token 数（TPS，tokens per second）](https://broadrouter.com/zh/glossary/tokens-per-second/)

每秒 token 数（TPS）是语言模型生成输出 token 的速率，通常针对单个请求、在首个 token 到达之后测量。它决定了回复开始后流得有多快。把所有并发请求加起来就是系统吞吐量；首个 token 之前的等待时间则单独测量。

## 常见问题

### 大模型 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 则关闭重试。

## 相关指南

-   [对话补全的流式输出，以及连接中断的处理](https://broadrouter.com/zh/guides/streaming-chat-completions/)
-   [用 IP 白名单把 API 密钥锁定到你的服务器](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/)
-   [用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)

用你的真实业务负载试一试。 新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-errors-and-retries&utm_content=page-cta) ·

**来源**

-   [BroadNet Inference API 参考文档：错误与重试 （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-errors-and-retries&utm_content=sources#errors)
-   [BroadNet Inference API 参考文档：限制 （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-errors-and-retries&utm_content=sources#limits)
-   [OpenAI Python SDK README：重试与超时（核对于 2026-11-14）](https://github.com/openai/openai-python#retries)
