超时、重试与幂等
三件事分开配、哪些错误可以重试、退避与抖动、幂等键为什么比重试更重要。
内容最后核对:2026-11-18
本页目录
三件事分开配
混在一起就会变成「偶发重复扣费」:超时是客户端等多久,重试是失败后做什么, 幂等是重试会不会产生第二笔单。
超时
| 动作 | 建议 | 为什么 |
|---|---|---|
| 连接超时 | 5–10 秒 | 连不上要尽快换路,不要等 60 秒才发现 |
| 读超时(文本) | 60–120 秒 | 长上下文本来就慢 |
| 读超时(同步出图 / 出音) | 180–300 秒 | 网关已经把上游超时压在上限内,客户端别提前放弃 |
| 异步提交 | 60 秒 | 提交是一次短请求(只做受理) |
| 异步轮询 | 30 秒 | 轮询幂等,随便重试 |
客户端超时应该比网关的上游超时更长,否则你会先放弃,而服务端还在跑 —— 那次调用会照常计费,你却以为失败了。
哪些错误可以重试
| 可以 | 不要 |
|---|---|
channel.unavailable(503) | auth.*(401 / 403) |
upstream.rate_limited(429) | quota.*(402) |
upstream.timeout(504) | model.*(404 / 409) |
upstream.unreachable(502) | validation.failed(400) |
任何 GET 轮询 | price.stale(409) |
| 带同一幂等键的视频 / 音乐提交 | 不带幂等键的提交 |
判据:重试之后结果会不同吗? 会(上游临时故障、限流退避)就重试;不会(余额、参数、权限) 就别重试 —— 重试一万次结果一样,而 402 的唯一处置是充值。
退避
第 1 次失败 → 等 1 秒(± 抖动)
第 2 次 → 3 秒
第 3 次 → 8 秒
之后 → 放弃并报错(不要无限重试)
- 加抖动(随机 ±30%):几百个客户端同时重试会形成新的尖峰,把上游再打挂一次。
- 429 时优先看响应里有没有
Retry-After,有就按它等。 - 最多 3 次。第 4 次开始,成功的概率已经很低,而每次都在花你的配额。
幂等键
视频与音乐的提交是真扣费。没有幂等键时,超时后的第一次重试就是一笔新订单,而响应看起来
完全正常(一个新的 task_id)。
import requests
def submit(prompt: str, order_id: str):
return requests.post(
f"{BASE}/video/generations",
headers={**H, "Idempotency-Key": order_id}, # 同一个业务单号,重试不变
json={"model": VIDEO_MODEL, "prompt": prompt, "duration": 5},
timeout=60,
)
- 键由你生成并保持一致(订单号、业务主键都行)。
- 不要每轮重试换一个新键 —— 那等于没开幂等。
- 同一个键 + 同一个请求体 → 返回同一个任务;同一个键 + 不同请求体 →
409。 - 留空 = 每次重试都真下一单。这一条比其它所有重试建议都重要。
一次完整的提交 + 轮询
import time, requests
def run_video(prompt, order_id, timeout=900):
r = submit(prompt, order_id)
if r.status_code == 502: # 上游拒绝;预扣已全额释放
raise RuntimeError(f"submit failed: {r.text}")
r.raise_for_status()
job = r.json() # {"task_id": "...", "status": "queued"}
deadline, interval = time.time() + timeout, 5
while time.time() < deadline:
cur = requests.get(f"{BASE}/video/generations/{job['task_id']}",
headers=H, timeout=30).json()
if cur["status"] == "completed":
return cur
if cur["status"] == "failed":
# error.code 区分原因:job.link_expired 可续期,其余要重新生成
raise RuntimeError(f"job failed: {cur.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30) # 退避到 30 秒封顶
raise TimeoutError(job["task_id"])
注意这段代码里没有「failed 就重提」:重提是一次新的扣费,要不要重提是你的业务判断,
不是重试策略。
别做的事
- 不要在
POST上做无限重试。 哪怕有幂等键,无限重试也只是把上游的故障变成你的账单。 - 不要把 402 当临时故障。 余额不足重试不会好。
- 不要在流式响应里重试。 已经吐出去的 token 收不回来。
- 不要把「提交成功」当成「任务成功」。 提交只表示受理,结果要看终态。