客户端重试的范围与预算
重试只针对可重试的错误：429、502、503 与连接失败；参数错误这类问题重试多少次都不会成功。重试要用指数退避，并设定总次数与总时长的预算，否则重试本身会放大故障。流式请求中断后重试，还要注意重复输出的问题。
基本信息
| 可重试 | 429、502、503、连接失败 |
|---|---|
| 不可重试 | 参数与鉴权类错误 |
| 退避策略 | 指数退避加随机抖动 |
| 预算 | 次数上限加总时长上限 |
| 流式注意 | 防止重复输出 |
典型使用场景
- 网关切换实例时客户端的自动恢复
- 过载期间的平滑退避
- 批量任务的重试策略设计
- 避免重试把已经过载的服务再压一遍
- 把可重试与不可重试的错误码整理成一页说明交给客户端团队
- 把重试参数写进客户端默认配置，避免各团队各写一套
SDK 用法
SDK 用法
from openai import OpenAI
client = OpenAI(base_url="http://<网关>/v1", api_key="<KEY>",
max_retries=2, timeout=600.0)
# 官方 SDK 对部分错误会自动退避重试，可按需覆盖
# 业务侧建议携带请求幂等键，便于重试与人工重发时去重分错误类型处理
| 错误 | 是否重试 | 说明 |
|---|---|---|
| 429 | 是，先退避 | 按提示等待 |
| 502/503 | 是，可换实例 | 排除坏实例 |
| 400/401 | 否 | 重试不会成功 |
| 超时 | 谨慎 | 可能已扣费且已生成 |
业务侧建议携带请求幂等键：重试与人工重发都能据此去重，这是避免重复计费最省事的做法。
重试预算要覆盖整条链路：客户端重试乘上网关重试，实际请求量可能放大好几倍，必须限制总次数。
重试要区分场景：交互请求重试太久会让用户一直等，应该设更短的超时；批量任务可以放宽。
把重试次数与最终失败率放在一起监控：重试率上升往往是上游问题的早期信号。