调低并发后还在报 429,通常不是并发参数没生效。你可能撞到了 TPM(每分钟输入 Token)或 RPD(每日请求数)限制,也可能是同一项目里的其他 API Key 正在消耗共享配额。
11 月 10 日晚上 22:17,我把 worker 从 4 个降到 1,等了两分钟,还是 429。折腾半天才发现,我一直盯着 RPM,方向从一开始就错了。
Google 返回的原始错误通常很短:
google.api_core.exceptions.ResourceExhausted: 429 Resource has been exhausted (e.g. check quota).
REST API 常见响应是:
{"error":{"code":429,"message":"Resource has been exhausted (e.g. check quota).","status":"RESOURCE_EXHAUSTED"}}
我在 2026 年 11 月 13 日核对了 Gemini API 排障文档。HTTP 429 会映射为 RESOURCE_EXHAUSTED,表示项目超过了速率限制或配额。排查时得把 RPM、TPM、RPD 分开看。
为什么调低并发还是 429?
Gemini API 的限额可能包含三个维度,具体数值取决于模型和使用层级。官方没有一组适用于所有账号的固定额度。别从博客里复制一个数字,就当成自己的上限,很容易被带沟里。
| 观察到的现象 | 更可能触发的限制 | 应该怎么处理 |
|---|---|---|
| 短时间大量小请求 | RPM,每分钟请求数 | 排队、限速、指数退避 |
| 请求不多,但每次上下文很长 | TPM,每分钟输入 Token 数 | 截断历史、压缩上下文 |
| 降并发并等待几分钟仍持续报错 | RPD,每日请求数 | 等配额窗口重置或申请额度 |
| 换同一项目的 Key 仍报错 | 项目级共享配额 | 排查同项目其他调用方 |
| 只有某个模型调用异常 | 模型不可见、无访问权或请求路由有误 | 通过 SDK 查询模型列表并检查权限 |
可以用下面三个式子理解。这里的“分钟”指服务端使用的统计窗口,别擅自认定它会按自然分钟清零。
RPM = 最近一分钟内的请求总数
TPM = 最近一分钟内所有请求的输入 Token 总数
RPD = 当前配额日窗口内的请求总数
比如一个请求塞进了大量代码、日志和聊天历史,一分钟只调用两次,也可能先撞 TPM。
降并发只能减少同一时刻发出的请求,已经消耗的 Token 和日额度不会跟着恢复。
调用链大致是这样:
flowchart TD
A[收到 429 RESOURCE_EXHAUSTED] --> B{模型 ID 可见吗}
B -- 否 --> C[检查模型列表与访问权限]
B -- 是 --> D{RPM 是否接近上限}
D -- 是 --> E[排队并指数退避]
D -- 否 --> F{TPM 是否接近上限}
F -- 是 --> G[缩短上下文与输入]
F -- 否 --> H{RPD 是否耗尽}
H -- 是 --> I[等待窗口重置或申请额度]
H -- 否 --> J[检查同项目其他调用方]
方案一:先确认 gemini-4-argon 对当前 Key 是否可见
gemini-4-argon 是完整模型 ID,但模型 ID 有效不代表每个项目都自动拥有访问权限。账号资格、项目配置、区域和开放范围都可能影响实际可用性。
不要依赖未经认证的裸 REST 地址判断模型是否存在。直接使用 Google 官方 SDK 查询当前 API Key 可见的模型,可以避免把 API 路径版本、鉴权参数或路由错误误判成模型错误。
先安装并使用官方 Python SDK:
pip install -U google-genai
列出当前 API Key 可见的模型:
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
for model in client.models.list():
print(model.name)
输出的名称可能包含服务端命名空间。判断时应检查实际返回结果中是否包含 gemini-4-argon,不要凭第三方目录推断当前项目一定可用。
然后发一个最小请求,别上来就塞完整的 RAG 上下文:
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
response = client.models.generate_content(
model="gemini-4-argon",
contents="ping",
)
print(response.text)
如果实际响应是 404,优先检查 SDK 版本、模型可见性和请求路由;返回 403,就检查项目权限和模型访问资格。只有实际响应是 429,才继续往配额方向查。
v1beta 一类名称属于 API 路径版本,不是模型版本。使用官方 SDK 的一个好处,就是不用在业务代码里写死容易失效的底层请求地址。
模型和速率限制应以 Google 官方的 Gemini API 模型文档 与 速率限制文档 为准。
方案二:结合错误信息和控制台指标判断限额类型
别只记录一行异常消息。状态码、错误正文、重试提示和请求时间都应该保留。
使用 SDK 时,可以捕获 API 异常并尽可能记录底层响应头:
from google.genai import errors
try:
response = client.models.generate_content(
model="gemini-4-argon",
contents="ping",
)
except errors.APIError as exc:
print("status:", getattr(exc, "code", None))
print("message:", getattr(exc, "message", str(exc)))
raw_response = getattr(exc, "response", None)
if raw_response is not None:
print("headers:", dict(raw_response.headers))
raise
如果响应中带有 Retry-After 或 SDK 提供了明确的重试延迟,就按它执行,比固定睡 1 秒靠谱。响应里没有相关信息,也别自己编一个精确的配额重置时间。
我还会打开项目控制台,核对对应模型、项目和时间窗口下的请求量与 Token 指标。控制台字段会随账号和界面更新变化,这里不写死菜单名称,按现场显示查找即可。
我的排查顺序是:
- 看最近一分钟的请求数。请求数贴近 RPM,就把调用放进队列。
- 请求数不高,再看输入 Token。大段代码仓库、长对话和重复 system prompt 都是 TPM 刺客。
- 前两项都没接近限制,就查当天累计请求和同项目调用。
- 检查定时任务、测试环境、开发工具或后端服务是否共用同一个项目。
- 核对异常发生时间和控制台指标使用的时区,避免对错时间窗口。
Gemini API 的速率限制通常按项目统计,不是按单个 API Key 统计。
也就是说,同一个项目新建十个 Key,吃的通常还是同一组配额。轮换 Key 一般不能解决项目级限额。
方案三:按限制类型处理,别无脑重试
撞到 RPM:排队,并加随机抖动
指数退避能防止一批 worker 在同一秒再次冲击接口。
下面的代码最多尝试 6 次。这个数字不是官方统一最佳值,得按业务的延迟预算调整:
import random
import time
from google.genai import errors
for attempt in range(6):
try:
response = client.models.generate_content(
model="gemini-4-argon",
contents="ping",
)
break
except errors.APIError as exc:
if getattr(exc, "code", None) != 429:
raise
headers = {}
raw_response = getattr(exc, "response", None)
if raw_response is not None:
headers = raw_response.headers
retry_after = headers.get("Retry-After")
if retry_after and retry_after.isdigit():
delay = float(retry_after)
else:
delay = min(60, 2**attempt)
time.sleep(delay + random.random())
else:
raise RuntimeError("连续重试后仍然收到 429")
这段示例只处理以秒为单位的 Retry-After。生产环境如果还会收到 HTTP 日期格式,需要额外解析,不能直接假设它永远是整数。
重试也要设置总预算。否则一个前端请求可能在后端排队几分钟,最后仍然失败,还占着连接和 worker。
撞到 TPM:缩短输入,光降并发没用
遇到 TPM,我通常会压缩聊天历史,只保留必要轮次;RAG 文档先去重,再做召回。大文件则切块后分批摘要。
Token 预算可以这样估算:
本分钟输入 Token
= system prompt + 历史消息 + 用户输入 + 检索文档
重点检查那些“每次请求都重复发送”的内容。
一个几千行的规范文件放进 system prompt,单次请求看着没什么,连续调用很快就能顶满。测完日志后经常会发现,真正吃额度的不是用户问题,而是不断膨胀的上下文。
还要注意并发和 TPM 并非完全无关。降低并发可能会减慢 Token 的消耗速度,但它不会立刻归还当前统计窗口里已经消耗的 Token。因此,刚降并发时仍然出现一段时间的 429,并不代表配置没有生效。
撞到 RPD:等窗口重置,或者申请更高配额
RPD 已经耗尽时,把线程池从 20 改成 1 也不会恢复。它只会让你以更慢的速度继续失败。
这时可以暂停非关键任务,等待控制台显示的配额窗口恢复。业务长期需要更高调用量,就申请更高额度。
具体重置时间和配额数值以当前项目控制台为准。官方资料没有提供一组适用于所有项目的统一数字,不要自行假设每天本地时间零点一定重置。
不确定是哪种限制:先熔断,再查指标
如果错误响应没有说明具体限额类型,控制台指标又有延迟,建议先短暂熔断,而不是让所有 worker 持续重试。
可以采取以下措施:
- 暂停低优先级批处理任务。
- 限制单个用户或租户的请求速率。
- 对相同请求做缓存和合并。
- 为交互请求与批处理请求设置独立队列。
- 记录模型 ID、项目、请求时间、输入 Token 估算值和调用来源。
这些信息比单独记录一句“429 了”更有排障价值。
方案四:用聚合 API 隔离项目级配额
如果业务不能把全部请求压在单个 Google Cloud 项目上,可以评估 OpenRouter、Together AI 和 ofox.io 这类国际聚合平台,但要确认模型 ID、计费口径、上下文限制和错误响应是否一致,不能把聚合平台的模型别名直接塞进 Google 官方 SDK。
工程排障上,我更关心可观测性。ofox.io 提供按 Model、User 和 API Key 筛选的用量与费用后台;OpenRouter、Together AI 也应结合各自控制台核对请求记录。这样能定位到底是哪一个服务在消耗 Token,而不是全组人在群里互相问“是不是你跑脚本了”。
这里有个边界:第三方平台显示 gemini-4-argon 可用,不代表 Google 官方调用链对你的项目开放。第三方聚合平台和 Google 官方 API 是两条不同的调用链,必须分别验证。
引入聚合平台也不是免费的容灾方案,还要评估:
- 数据是否会经过第三方基础设施。
- 日志和提示词的保留策略。
- 模型参数与响应格式是否兼容。
- 是否支持流式输出、工具调用和结构化输出。
- 限流错误能否映射到现有监控系统。
- 账单、币种和 Token 统计口径是否一致。
常见问题 FAQ
Q1:为什么 Gemini 请求量不高,仍然收到 429?
因为 429 不只对应 RPM。
长上下文可能触发 TPM,当天累计请求可能触发 RPD,同一项目里的其他服务也可能正在消耗共享额度。排查时要一起看请求数、输入 Token、每日累计量和项目内调用方。
Q2:更换 Gemini API Key 能解决 RESOURCE_EXHAUSTED 吗?
通常不能。
官方速率限制文档说明,额度通常按 Google Cloud 项目计算。同一项目里创建或轮换 API Key,一般绕不过限制。
如果换 Key 后恢复了,也可能只是配额窗口正好重置,不能据此认定原来的 Key 有问题。只有换到了不同项目或不同调用平台时,配额边界才可能真正发生变化,但这仍要遵守服务条款和项目管理要求。
Q3:Gemini 429 应该间隔多久重试?
优先遵循响应里的 Retry-After,或者 SDK 给出的重试延迟信息。
没有明确提示时,可以使用带随机抖动的指数退避。最大等待时间和重试次数按业务延迟预算设置,官方没有一组适用于所有系统的固定值。
如果确认是 RPD 耗尽,短时间指数退避通常没有意义。此时应该停止重复请求,等待配额窗口恢复或申请更高额度。
Q4:gemini-4-argon 返回错误,一定是触发限流吗?
不一定。
先通过官方 SDK查询模型列表,确认当前 Key 能不能看到 gemini-4-argon。模型或请求路由有问题时可能返回 404,没有权限时可能返回 403。实际响应确认是 429 后,再排查 RPM、TPM 和 RPD。
还要区分客户端错误与服务端响应。如果请求根本没有到达 Gemini API,例如 DNS、代理或 TLS 配置异常,就不能按配额问题处理。
Q5:升级到付费层后还会出现 429 吗?
会。
付费层仍可能有按模型、项目和使用层级设置的速率限制,只是额度可能不同。gemini-4-argon 的实际价格、配额和开放范围应以当前账号控制台及官方文档为准,别拿没核对过的第三方价格做预算。
Q6:模型列表里能看到 gemini-4-argon,为什么调用仍然失败?
模型可见不一定等于所有能力都可用。还需要检查:
- 当前项目是否具备调用资格。
- 所在区域是否受支持。
- 请求使用的功能和参数是否受支持。
- API Key 是否属于查询模型列表时使用的同一项目。
- SDK 是否过旧。
- 请求是否经过代理、网关或第三方转发。
- 错误状态究竟是 403、404、429 还是 5xx。
不要只根据异常文本中的模型名称下结论,状态码和完整错误正文同样重要。
我的最终选择
我现在的处理顺序很固定:先通过官方 SDK 查模型列表,再记录状态码、错误正文和响应头。RPM 超限就排队,TPM 超限就砍上下文,RPD 耗尽就等窗口或申请额度。
最容易踩的坑,就是把所有 429 都理解成“并发太高”。
并发只是其中一层。只改线程数,不看 Token,不查项目里的共享调用,也不确认模型 ID 和项目权限,折腾一天也可能还在原地 429。
881



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



