# OpenAI API 报错 429 怎么办？Python 重试与并发控制

> 遇到 OpenAI API 429，先区分限流、余额与额度问题，再配置 Python SDK 重试、等待间隔和任务队列，避免重复重试放大请求量。

- 原文：https://token.help/articles/openai-api-429-retry-guide
- 作者：词元有方编辑部
- 成稿时间：2026-09-29T07:46:10.000Z
- 发布时间：2026-09-29T07:58:53.000Z
- 最后更新：2026-09-29T07:58:53.000Z
- 分类：接入教程
- 核验方式：已核对官方文档
- 核验时间：2026-09-29T00:00:00.000Z
- 适用版本：OpenAI Cookbook、Python SDK 与错误码在线文档（2026-09-29 核对）

引用本文请使用上方原文链接；配置与结论以文中版本和核验时间为准。来源内容的许可说明保留在正文中。

批量调用大模型时，单条请求能够成功，并不意味着把并发开大后仍然稳定。

遇到 `429`，第一步是查看响应中的错误详情。OpenAI 的 `429` 可能表示请求过快，也可能与余额、消费上限或使用额度有关。后几种情况，重复发送请求无法恢复访问。[官方错误说明](https://developers.openai.com/api/docs/guides/error-codes)

本文根据 OpenAI Cookbook 与当前 SDK 文档编译整理，补充任务队列建议。示例用于说明配置方式，未执行真实 API 请求；第三方服务的错误码和重试规则需按其文档核对。

## 1. 确认是哪一种 429

先保留错误的 `code`、`message` 和请求 ID，再决定处理方式。排查日志不要记录 API Key。

| 情况        | 处理方向         |
| --------- | ------------ |
| 请求发送过快    | 降低发送速度，等待后重试 |
| 短时间流量增长过快 | 降低流量，再逐步增加   |
| 余额不足      | 检查账户余额       |
| 达到消费或使用上限 | 检查对应限制       |

如果响应包含 `Retry-After`，应按它指示的时间等待。通过第三方 API 服务调用时，还需要核对该服务自己的错误定义。[官方排查说明](https://developers.openai.com/api/docs/guides/error-codes)

## 2. 先检查 SDK 已有的重试

OpenAI Python SDK 默认会对部分错误自动重试两次，其中包含 `429`。可以通过 `max_retries` 调整，设置为 `0` 则关闭自动重试。[Python SDK 重试说明](https://github.com/openai/openai-python#retries)

因此，加入新的重试库之前，先确认现有配置。SDK 按状态码重试，不意味着余额或额度问题也能通过等待恢复。

下面演示 SDK 参数的配置位置。先安装 `openai` 包，并在运行环境设置 `OPENAI_API_KEY` 和 `OPENAI_MODEL`；模型 ID 需选择账户实际可用、支持 Chat Completions 的模型。

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    max_retries=2,
    timeout=30.0,
)

response = client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    messages=[
        {"role": "user", "content": "用一句话解释什么是 API。"}
    ],
)

print(response.choices[0].message.content)
```

本例默认连接 OpenAI 官方地址。使用第三方兼容接口，需要额外配置其 `base_url`，以及该服务的密钥和模型 ID，具体可参考 [Python OpenAI SDK 配置第三方 API](https://token.help/articles/python-openai-sdk-tokendance)。

如果外层程序也会重试，需要计算两层重试叠加后的尝试次数。例如，外层尝试三次，每次内部最多发送三次，一个任务就可能触发九次请求。建议明确由哪一层负责重试，避免等待时间和请求数失控。

## 3. 重试之间留出间隔

OpenAI Cookbook 推荐使用带随机延迟的指数退避：连续失败时，逐渐延长等待时间，并加入随机变化，减少多个任务同时再次发送请求的情况。

同时要设置停止条件。失败请求也可能占用速率额度，立即、无限地重发请求会让恢复更困难。[原文：How to handle rate limits](https://developers.openai.com/cookbook/examples/how_to_handle_rate_limits)

自行编写重试逻辑时，可以把最大尝试次数和总等待时间一起作为预算；如果服务端要求的等待时间超出任务预算，就把任务留待稍后处理，而不是提前重发。

## 4. 批量任务先控制发送速度

假设你要处理一批文章，可以采用这样的任务流程：

```text
待处理文章
    ↓
进入任务队列
    ↓
按设定速度发送请求
    ↓
成功 → 保存结果
临时限流 → 等待后有限重试
余额或额度问题 → 暂停并处理账户问题
重试耗尽 → 保存失败任务
```

并发限制和发送速率最好分别管理：限制同时执行的任务数，并不一定能限制每分钟的请求量。请求返回很快时，即使并发很低，也可能持续发出大量请求。

可以从小批量开始，观察失败原因和处理速度，再调整发送节奏。为每个任务保留独立 ID，保存成功结果，失败任务单独重跑，避免一个任务失败后整批重新请求。

## 5. 记录重试有没有帮助

每批任务至少记录：

- 原始任务数与成功数。
- 实际请求次数与重试次数。
- 最终失败原因。
- 总耗时。

如果成功率没有改善，请求次数却明显增加，就应该继续降低发送速度或排查限制，而不是继续增加重试次数。

**处理 429 的顺序是：看清原因、管理发送速度，再用有限重试处理临时失败。**

## 参考资料与许可

- OpenAI Cookbook：[How to handle rate limits](https://developers.openai.com/cookbook/examples/how_to_handle_rate_limits)。
- OpenAI Python SDK：[Retries](https://github.com/openai/openai-python#retries)。
- OpenAI API：[Error codes](https://developers.openai.com/api/docs/guides/error-codes)。

Cookbook 编译参考部分遵循其 MIT 许可；原版权归 OpenAI 所有。本文补充了任务队列建议和 SDK 配置示例，并非原文全文翻译。许可仅对应 Cookbook 材料，不代表上述所有网站采用相同许可。

### OpenAI Cookbook 许可声明

```text
MIT License

Copyright (c) 2025 OpenAI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

[查看上游许可文件](https://github.com/openai/openai-cookbook/blob/main/LICENSE)。

## 核验参考来源

- https://developers.openai.com/cookbook/examples/how_to_handle_rate_limits
- https://github.com/openai/openai-python#retries
- https://developers.openai.com/api/docs/guides/error-codes