---
title: 超时、限流与重试
description: 配置 SDK 超时和有限重试，区分可重试错误与配置错误，避免重复提交。
---

<aside className="docs-publication" data-pagefind-ignore>文档由 <a href="https://1zheai.com/editorial/#publisher">1折AI</a> 维护。<a href="https://1zheai.com/editorial/">来源、商业关系与纠错说明</a>。发现错误，请向 <a href="mailto:support@1zheai.com">support@1zheai.com</a> 提供页面地址与可核查依据，不要发送密钥或账号资料。</aside>

先修正配置错误，再处理临时故障。把重试次数、并发和总等待时间一起限制，避免短时间内把同一个失败请求重复发送很多次。

## 哪些情况应该重试

| 情况 | 建议 |
| --- | --- |
| 400 / 401 / 403 / 404 | 先修正请求、权限或模型；不自动重复原请求 |
| 429 | 查看响应提示；有 `Retry-After` 时遵循等待时间并降低并发 |
| 500 / 502 / 503 / 504 / 529 | 可以有限重试；持续失败则停止并反馈请求 ID |
| 连接失败 | 检查 DNS、代理与网络，按任务允许的时间有限重试 |
| 请求发出后的超时或断流 | 结果可能不确定，先核对日志；不能假定上游尚未处理 |

客户端库的重试范围不一定与上表完全相同。使用哪一层重试，就在那一层明确设置策略。

## 先用 SDK 内置重试

Python 与 Node.js 的超时单位不同：Python 使用秒，Node.js 使用毫秒。下例设置 120 秒超时和最多 2 次自动重试；首次接入排错时可以改为 0。

<CodeGroup>
```python title="Python"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEZHE_API_KEY"],
    base_url="https://1zheai.com/v1",
    timeout=120.0,
    max_retries=2,
)
```
```javascript title="Node.js"
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ONEZHE_API_KEY,
  baseURL: "https://1zheai.com/v1",
  timeout: 120_000,
  maxRetries: 2,
});
```
</CodeGroup>

超时配置不是整个业务任务的总耗时上限：重试和等待会增加总耗时。如果外层还会重新执行任务，应另外设置总截止时间与取消机制。

## 自己实现重试时

关闭 SDK 自动重试，避免叠加。使用逐步增加的等待间隔并加入随机抖动；明确限制尝试次数、最长等待和并发队列。解析 `Retry-After` 时注意它既可能是秒数，也可能是 HTTP 日期。

如果已经向用户展示部分流式结果，不要自动从头重放并接在旧文本后面。保留“未完成”状态，让用户决定重新生成或继续。

图片生成、工具执行和其他可能产生外部结果的任务，要特别注意重复提交。不能假设设置某个任意的请求 ID 就能让服务端自动去重。

## 记录足够的排错信息

记录时间、端点、模型、状态码、耗时、尝试序号和服务端返回的请求 ID。避免记录认证请求头与完整私人提示词。用这些信息对照[调用日志](/docs/usage-logs/)。

SDK 设置分别参考 [OpenAI Python SDK](https://github.com/openai/openai-python#retries) 和 [Node SDK](https://github.com/openai/openai-node#retries)。具体错误见[错误码与排错](/docs/troubleshooting/)。