文档指南错误处理与重试
错误处理与重试
按状态码分支、指数退避重试，让集成经得起限流与上游抖动。
两条原则：按 HTTP 状态码与错误 type/status 字段分支（错误文案是本地化的，匹配文本必然踩坑）；只重试值得重试的——参数错误重试一万次也不会变对。
按状态码的处置
| HTTP | 典型原因 | 处置 |
|---|---|---|
| 400 | 请求体格式错误、缺字段 | 修请求，不重试。 |
| 401 / 403 | Key 无效/停用/IP 拦截 | 检查 Key 与配置，不重试。 |
| 402 | 余额或 Key 额度用尽 | 充值/调额度，不要自动重试（结果不会变）。 |
| 404 | 模型不存在/入口不支持 | 对照模型列表检查拼写。 |
| 413 | 请求体过大 | 压缩内联媒体或换接口，不重试。 |
| 429 | RPM/并发限流 | 指数退避 + 抖动后重试。 |
| 502 / 503 | 上游故障/网关过载 | 退避后重试；网关本身也会先做故障转移。 |
指数退避示例
import random
import time
from openai import OpenAI, APIStatusError
client = OpenAI(api_key="sk-sole-...", base_url="https://api.soleapi.com/v1")
RETRYABLE = {429, 502, 503}
def create_with_retry(**kwargs):
delay = 1.0
for attempt in range(5):
try:
return client.responses.create(**kwargs)
except APIStatusError as e:
if e.status_code not in RETRYABLE or attempt == 4:
raise
time.sleep(delay + random.random()) # jitter
delay = min(delay * 2, 30)OpenAI 与 Anthropic 官方 SDK 自带对 429/5xx 的自动重试（max_retries 参数），多数场景直接用即可；自己写重试时务必加抖动，避免多个客户端同拍重试形成惊群。