超时、限流与重试

配置 SDK 超时和有限重试，区分可重试错误与配置错误，避免重复提交。

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

哪些情况应该重试

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

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

先用 SDK 内置重试

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

Python
Node.js

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,
)

import OpenAI from "openai";

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

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

自己实现重试时

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

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

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

记录足够的排错信息

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

SDK 设置分别参考 OpenAI Python SDK 和 Node SDK。具体错误见错误码与排错。