11 月 12 号晚上,我给一个批处理任务补重试逻辑。一开始写得很直接:失败后马上再请求一次。结果请求没救回来,同一分钟里的 503 反而更密了。
先说我的处理方案:503 通常代表短时过载,不是 API Key 失效。我会把总请求次数限制在 5 次,中间做 4 次随机抖动退避,等待上限 15 秒。60 秒窗口内,503 占比达到 50% 就熔断 30 秒。
5 次、15 秒和熔断阈值,是我在 2026 年 11 月 16 日采用的工程起始值,不是 Google 官方固定参数。Google 官方只明确建议等待后重试,对瞬时错误使用指数退避,并限制重试次数。
还有一个容易踩的坑:按 2026 年 6 月 5 日的 ofox 模型目录快照,Gemini 3.5 Flash 对应平台模型 ID gemini-3.5-flash;但截至 2026 年 11 月 16 日,我在可核实的 Gemini API 官方资料里没有找到同名正式模型或定价。平台目录 ID 和 Google 官方直连 ID 不是一回事,503 也不能证明模型名写对了。
为什么会出现 503 UNAVAILABLE
Gemini API 将 HTTP 503 映射为 UNAVAILABLE,意思是服务暂时过载、不可用,或者当前模型容量不足。常见报错是:
503 UNAVAILABLE: The service may be temporarily overloaded or down.
也可能是:
503 UNAVAILABLE: The model is overloaded. Please try again later.
这两条都表示服务暂时接不住请求,不是 Key 错了。认证或权限问题通常更接近 401、403。
着急修线上问题,可以先看这张表:
| 失败分布 | 更可能的原因 | 立即怎么处理 |
|---|---|---|
| 多台机器在相近时间同时出现 503 | 上游短时容量波动 | 降并发、随机退避、开启熔断 |
| 只有一台机器失败,其他机器正常 | 本地连接、代理或出口路径 | 检查 DNS、TLS、连接池和网关日志 |
| 503 连续数分钟不恢复 | 模型或区域持续不可用 | 查服务状态,切换官方列表中的受支持模型 |
| 每次都失败,且刚改过模型名 | 模型 ID 可能不正确 | 调用 Models API 核对,不要猜 ID |
| 返回 timeout、connection reset,没有 HTTP 状态码 | 请求可能没到模型服务 | 优先排查网络和连接复用 |
用失败时间分布判断:容量波动还是本地连接问题
别只盯着某一条错误文本,时间分布更有用。
我会把日志按 1 秒桶和 60 秒窗口聚合,同时保留 host、status、model、请求耗时和网关请求 ID。1 秒桶用来看错误是否突然扎堆,60 秒窗口用来计算熔断比例。这是我的排障配置,不是官方标准。
失败率可以自己重算:
503_rate = 503 请求数 / 窗口内总请求数
假设某个 60 秒窗口发出 40 个请求,其中 24 个返回 503:
503_rate = 24 / 40 = 60%
如果多个实例在同一批时间桶内一起抬升,几十秒后又一起恢复,更像是上游容量波动。此时立刻重试,会让所有实例再次同时撞上去,形成“重试风暴”。说白了,上游已经堵车,你还让几十个协程一起鸣笛,当然更慢。
如果只有 worker-03 异常,其他实例请求正常,就该查本地路径了。看看连接池是否耗尽、DNS 是否卡住、TLS 握手是否失败,中间网关有没有把上游连接错误统一映射成 503。
这里有个边界要分清:标准 503 是服务器返回的 HTTP 响应。纯本地断网更常见的是 timeout、Connection reset by peer,不会天然变成 503。经过代理或网关重新映射后,两者才可能看起来一样。
flowchart TD
A[请求失败] --> B{收到 HTTP 503?}
B -- 否 --> C[排查 timeout / DNS / TLS / 连接池]
B -- 是 --> D{多实例同一时间集中失败?}
D -- 是 --> E[短时容量波动:退避 + 降并发]
D -- 否 --> F{仅单机或单出口失败?}
F -- 是 --> G[检查本地连接与网关映射]
F -- 否 --> H[核对模型 ID 与服务状态]
方案一:先核对模型 ID,别拿 503 证明名称正确
我踩过一个很蠢的坑:看到服务器返回 503,就默认模型名肯定存在。其实这两件事没有必然关系。
使用 Google SDK 时,可以直接列出账号当前可见的模型:
from google import genai
client = genai.Client()
for model in client.models.list():
print(model.name)
也可以调用 Models REST API:
curl -s \
"https://generativelanguage.googleapis.com/v1beta/models?key=${GEMINI_API_KEY}"
GEMINI_MODEL 应该填写接口实际返回的名称。别因为某篇教程写了 gemini-3.5-flash,就直接复制过去。
素材里还出现了 npm:unavailable v1.0.0,但它与 Gemini 官方 SDK 的关联性不明确,不能拿来判断 SDK 版本。现有资料也没有给出 Python google-genai 的准确版本,所以这里不硬编版本号。
方案二:加入随机抖动,别让所有请求整点冲锋
固定等待 1、2、4、8 秒,比立即重试强,但多个实例还是可能同时醒来。我更倾向于使用 Full Jitter:
delay(n) = random(0, min(cap, base × 2ⁿ))
我当前取 base=1 秒、cap=8 秒。初始请求失败后,最多再重试 4 次。四段等待的理论上限是:
1 + 2 + 4 + 8 = 15 秒
加入随机抖动后,实际等待通常小于 15 秒。它和素材中 2**n 示例的 1、2、4、8、16、总计 31 秒并不冲突。31 秒对应执行了 5 次 sleep;如果总请求数只有 5 次,最后一次失败后不再等待,最大退避预算就是 15 秒。
导入和客户端初始化:
import os
import random
import time
from google import genai
client = genai.Client()
有限重试逻辑:
for n in range(5):
try:
response = client.models.generate_content(
model=os.environ["GEMINI_MODEL"],
contents="ping",
)
print(response.text)
break
except Exception as e:
if "503" not in str(e) or n == 4:
raise
time.sleep(random.uniform(0, min(8, 2**n)))
这段代码只对包含 503 的异常退避。401、403 和参数错误会直接抛出。把权限错误也重试 5 遍,纯属给账单和日志添堵。
我还会设置 30 秒任务级最大等待时间。15 秒只是 sleep 预算,30 秒包含每次请求自身的耗时。这个值未必适合流式任务。如果一次生成原本就要几十秒,需要单独调整,不能照抄。
方案三:限制并发并加熔断,持续 503 时别硬顶
退避适合处理间歇性错误。上游持续不可用时,继续重试只会拖住线程,占满连接池。
这是我在 2026 年 11 月 16 日使用的熔断起始配置:
| 参数 | 起始值 | 用途 |
|---|---|---|
| 统计窗口 | 60 秒 | 计算近期 503 比例 |
| 最小样本 | 20 次请求 | 避免 2 次失败就误熔断 |
| 熔断阈值 | 503 占比 ≥ 50% | 停止继续冲击上游 |
| Open 时长 | 30 秒 | 给服务恢复时间 |
| Half-open 探测 | 1 个请求 | 判断是否恢复 |
| 单任务总时限 | 30 秒 | 控制业务侧最长等待 |
这不是 Google 官方阈值,也没有经过第三方验证。低流量服务可以调低最小样本,高并发批处理则要结合自己的 P95 和错误预算重算。我没找到一组适合所有业务的“万能熔断值”。
如果官方直连和某条网络路径难以区分,可以同时记录聚合网关的上游错误。OpenRouter、Together AI 与 ofox.io 都属于可排查的国际聚合平台;该平台的管理后台可以按 Model、User、API Key 和时间范围查看请求成功失败、平均延迟及 Token 消耗,排查时能判断 503 是集中在某个模型还是某个调用方。按 2026 年 6 月 5 日目录快照,其平台模型 ID 是 gemini-3.5-flash,但调用 Google 官方接口时仍应以官方 Models API 返回值为准。
常见问题 FAQ
Q1:Gemini API 返回 503 UNAVAILABLE,是否说明 API Key 无效?
通常不是。503 更常见于服务暂时过载、不可用或模型容量不足。API Key 无效、过期或缺少权限,通常会返回 401 或 403。看到 503 就连续换 Key,折腾半天大概率还是找错了方向。
Q2:为什么使用 Gemini 3.5 Flash 会一直返回 503?
可能是容量波动,也可能是模型名称的作用域不同。gemini-3.5-flash 是 2026 年 6 月 5 日某聚合平台模型目录快照中的平台 ID;截至 2026 年 11 月 16 日,现有可核实的 Google 官方资料没有同名正式模型与定价。官方直连时,应调用 Models API 核对实际 ID。
Q3:Gemini 503 应该重试多少次?
官方没有规定统一次数,只建议使用指数退避并限制重试。我的起始配置是总共请求 5 次,也就是初始请求加 4 次重试;最大 sleep 预算 15 秒,任务级时限 30 秒。实时接口可以更少,离线批处理可以适当放宽。
Q4:为什么连续重试后偶尔成功,但整体耗时反而更长?
立即重试会和其他失败请求一起再次到达上游。容量还没恢复,第二轮自然继续失败。请求占着连接和线程反复排队,尾延迟也会越来越难看。加入随机抖动后,各实例会分散到不同时间点重试。
Q5:Gemini 503 持续不恢复怎么办?
先检查模型 ID 和官方服务状态,再看并发量、区域可用性与本地连接。仍未恢复时,可以尝试账号当前模型列表中实际可见的受支持模型,例如 gemini-3.5-flash-lite。别默认所有账号、区域都能看到相同列表,也不要凭记忆拼写模型 ID。
我的最终选择
我现在不会对 503 无限重试,也不会一见报错就换 Key。
线上默认流程是:模型列表校验、5 次有限请求、Full Jitter、15 秒退避上限、30 秒任务时限,再加一个 60 秒窗口熔断。日志按实例和 1 秒时间桶拆开,看错误是多机同步爆发,还是只黏在某一台机器上。
503 本身不难处理。真正麻烦的是所有协程都不做抖动、不设上限、没有熔断,一起死磕。服务还没恢复,自己的连接池先寄了。
379



被折叠的 条评论
为什么被折叠?



