文档目录

超时、重试与幂等

三件事分开配、哪些错误可以重试、退避与抖动、幂等键为什么比重试更重要。

内容最后核对: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 收不回来。
  • 不要把「提交成功」当成「任务成功」。 提交只表示受理,结果要看终态。