先说结论
返回 429、"status": "RESOURCE_EXHAUSTED",意思是你的 Google Cloud 项目超过了某一项 Gemini API 限额:每分钟请求数(RPM)、每分钟输入 token(TPM)、每天请求数(RPD),或者付费档才有的按花费限流。谷歌的限额说明页写明,超过其中任何一项都会报这个错。
处理方法看你撞上的是哪一项:
- 每分钟限额: 等一下、按指数退避重试。官方 SDK 已经自带这个逻辑。
- 每天配额: 重试没用,要等到太平洋时间午夜重置。可以把项目升到付费档、换模型,或者等。
- 按花费限流(付费档): 放慢贵的请求,或者申请提额。
限额是按项目算的,不是按 API Key 算的,所以在同一个项目里新建 Key 还是会撞墙。如果你不想配置谷歌的计费,也可以通过 TeamoRouter 调 Gemini:一个按量付费的 Key,最低 $5 起充。
报错长什么样
下面是一个「每天配额」报错的正文,引自 google-gemini/gemini-cli#9248(2025 年 9 月,gemini-2.5-pro,免费档),这里去掉了转义,省略了 Help 链接部分:
{
"error": {
"code": 429,
"message": "You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits.\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 50\nPlease retry in 34.074824224s.",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.QuotaFailure",
"violations": [
{
"quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests",
"quotaId": "GenerateRequestsPerDayPerProjectPerModel-FreeTier",
"quotaDimensions": { "location": "global", "model": "gemini-2.5-pro" },
"quotaValue": "50"
}
]
},
{
"@type": "type.googleapis.com/google.rpc.RetryInfo",
"retryDelay": "34s"
}
]
}
}
报错里让你 34 秒后重试,但这是每天的配额,34 秒后重试还是会失败。真正靠得住的字段是 quotaId。
撞上的是哪个限额
看 google.rpc.QuotaFailure 里的 quotaId:
quotaId 里包含 |
限额 | 怎么办 |
|---|---|---|
PerMinute,比如 GenerateRequestsPerMinutePerProjectPerModel-FreeTier |
每分钟请求数或 token 数 | 退避,按 retryDelay 之后重试 |
PerDay,比如 GenerateRequestsPerDayPerProjectPerModel-FreeTier |
每天请求数 | 别再重试;等太平洋时间午夜,或换档、换模型 |
FreeTier |
免费档的限额 | 绑定计费账户后项目会升到第 1 档 |
谷歌自己的 Gemini CLI 会把 quotaId 里带 PerDay 或 Daily 的错误当成终止错误、不再重试(UKGovernmentBEIS/inspect_ai#5526 指出了对应代码)。如果报错里写着 limit: 0,说明这个项目对该模型根本没有配额;inspect_ai 项目遇到这种情况会直接失败,因为它意味着「这个模型或功能被完全限制了」(inspect_ai#3215)。
按花费限流。 付费档还有一个按滚动 10 分钟窗口计算的花费上限:第 1 档 $10,第 2 档 $200,第 3 档 $200(谷歌限额说明页,2026 年 11 月 18 日读取)。超过同样返回 429 RESOURCE_EXHAUSTED。谷歌的建议是等一下、少发贵的请求(缩短上下文、缩短输出),或者申请提额。
Gemini 4 很容易撞上第 1 档的花费上限。 Gemini 4 Argon 和 Carbon 首发价每百万输出 token $10,思考 token 也算输出。10 分钟内输出 100 万 token——一次长时间的 agent 任务或者几个并行任务就做得到——就已经是 $10,正好是第 1 档的全部额度。2026 年 12 月 1 日起这两个模型输出涨到每百万 $20,同样的上限一半的 token 就撞到了。Gemini 4 Hydrogen 是每百万输出 token $7.50。升到第 2 档需要累计付款 $100、且距第一次付款满 3 天。
这和余额用完不是一回事。 预付费余额到 $0 时,Gemini API 返回的是 402,不是 429。谷歌的排错指南说 402 完全不要重试,应该充值。
在谷歌那边怎么解决
- 先查你当前的限额。 限额因模型和档位而不同,在 Google AI Studio 里能看到。谷歌也说明了,公布的限额不做保证。
- 别在同一个项目里多建 Key。 限额按项目算,多出来的 Key 共用同一份配额。
- 每分钟限额就退避重试。 官方 Python SDK 会自己重试 429 和 5xx,最多 4 次,从约 1 秒开始、最长 60 秒。直接调 REST 的话,用带随机抖动的指数退避,并设置最大重试次数。
- 每天配额就直接停。 检测
quotaId里的PerDay,立刻失败:
from google import genai
from google.genai import errors
client = genai.Client()
def quota_ids(err: errors.APIError) -> list[str]:
body = err.details or {}
body = body.get("error", body)
ids = []
for detail in body.get("details", []):
if detail.get("@type", "").endswith("google.rpc.QuotaFailure"):
ids += [v.get("quotaId", "") for v in detail.get("violations", [])]
return ids
try:
resp = client.models.generate_content(model="gemini-3.8-flash", contents="Hello")
except errors.ClientError as e:
if e.code == 429 and any("PerDay" in q or "Daily" in q for q in quota_ids(e)):
raise RuntimeError("Daily Gemini quota used up; retrying won't help today") from e
raise
- 离开免费档。 绑定计费账户并预付至少 $5,免费项目就会升到第 1 档,谷歌说一般立即生效。更高的档位看累计花费和账户时长。
- 批量任务改用 Batch API。 Batch 请求有自己单独的限额,和交互式调用分开算。
改用 TeamoRouter 调 Gemini
如果你不想为项目配置谷歌计费,TeamoRouter 是另一种调 Gemini 的方式。它是一个 API 网关,一个 Key 就能调 Gemini、Claude、GPT 和 DeepSeek,从预充值余额里按量扣费,不用订阅。你谷歌项目的配额不受影响;用 TeamoRouter Key 发的请求从 TeamoRouter 余额里扣。
TeamoRouter 支持 Gemini 原生格式(/v1beta/models/{model}:generateContent)和 OpenAI 兼容的 /v1/chat/completions。
- 在 TeamoRouter 控制台创建一个 API Key,以
sk-teamo-开头。 - 充值,最低 $5。 支持银行卡,也支持 USDT、USDC 和 ETH。
- 调用 Gemini:
curl https://api.teamorouter.com/v1beta/models/gemini-4-hydrogen:generateContent \
-H "Authorization: Bearer sk-teamo-..." \
-H "content-type: application/json" \
-d '{"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]}'
用 Google Gen AI Python SDK 时,设置 base URL:
from google import genai
from google.genai import types
client = genai.Client(
api_key="sk-teamo-...",
http_options=types.HttpOptions(base_url="https://api.teamorouter.com"),
)
resp = client.models.generate_content(model="gemini-4-hydrogen", contents="Hello")
print(resp.text)
用 Gemini CLI 时,设置这三个变量(比如写在 ~/.gemini/.env 里):
GOOGLE_GEMINI_BASE_URL=https://api.teamorouter.com
GEMINI_API_KEY=sk-teamo-...
GEMINI_API_KEY_AUTH_MECHANISM=bearer
GET /v1/models 会列出能用的模型 ID,包括 gemini-4-hydrogen、gemini-4-carbon 和 gemini-4-argon。其余见 API 接入文档。
常见问题
每天的配额什么时候重置? 按谷歌限额说明页,每天请求数配额在太平洋时间午夜重置。
我新建了 API Key,还是报 429,为什么? 限额按项目算,不按 Key 算。同一个项目里的 Key 共用同一份配额。在 AI Studio 里看一下这个 Key 属于哪个项目。
每天配额的报错为什么写着「34 秒后重试」?
RetryInfo 里的延迟不区分每分钟和每天的限额。要用 quotaId 判断该不该重试。
429 RESOURCE_EXHAUSTED 是不是就是余额用完了? 不是。预付费余额用完返回 402。429 是撞上了速率或花费上限。
为什么用 Gemini 4 Argon / Carbon 特别容易报 429? 第 1 档每 10 分钟只能花 $10,而这两个模型首发价每百万输出 token 就要 $10(思考 token 算输出),12 月 1 日起涨到 $20。长任务或并行任务很快就会撞到这个上限。