博客

Gemini API 报 429 RESOURCE_EXHAUSTED 怎么办:是哪个限额、为什么换 Key 没用

先说结论

返回 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 链接部分:

text
{
  "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 完全不要重试,应该充值。

在谷歌那边怎么解决

  1. 先查你当前的限额。 限额因模型和档位而不同,在 Google AI Studio 里能看到。谷歌也说明了,公布的限额不做保证。
  2. 别在同一个项目里多建 Key。 限额按项目算,多出来的 Key 共用同一份配额。
  3. 每分钟限额就退避重试。 官方 Python SDK 会自己重试 429 和 5xx,最多 4 次,从约 1 秒开始、最长 60 秒。直接调 REST 的话,用带随机抖动的指数退避,并设置最大重试次数。
  4. 每天配额就直接停。 检测 quotaId 里的 PerDay,立刻失败:
python
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
  1. 离开免费档。 绑定计费账户并预付至少 $5,免费项目就会升到第 1 档,谷歌说一般立即生效。更高的档位看累计花费和账户时长。
  2. 批量任务改用 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。

  1. 在 TeamoRouter 控制台创建一个 API Key,以 sk-teamo- 开头。
  2. 充值,最低 $5。 支持银行卡,也支持 USDT、USDC 和 ETH。
  3. 调用 Gemini:
bash
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:

python
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 里):

bash
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。长任务或并行任务很快就会撞到这个上限。

相关阅读

准备好接入了吗?登录控制台 · 购买额度 · 创建 API Key,三步即可开始。