# Gemini API 已付费仍报 free_tier_requests limit 0：按实际请求恢复

> 恢复这类请求，先让运行进程使用正确付费项目的 Key，再完成该项目当前要求的计费或预付设置，并核对目标模型的有效配额。若这些条件都一致而错误仍为免费层 limit 0，停止轮换 Key，带脱敏证据联系支持。

- URL: https://blog.laozhang.ai/zh/posts/paid-tier-getting-free-tier-requests-limit-0
- Published: 2026-02-26
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 故障排查
- Tags: Gemini API, free_tier_requests, API 配额, 429 错误, Google AI Studio, 计费排查

---
Gemini API 明明已付费，却返回 `generate_content_free_tier_requests`、`limit: 0`，先检查**失败请求实际使用的 Key 所属项目**，不要只看浏览器里某个项目的 Tier 1 标签。把运行配置指向正确的付费项目，完成该项目当前要求的计费或预付设置，再查看同一模型的有效配额，这是恢复请求的起点。

如果实际 Key、项目、模型、计费状态和有效配额已经对齐，仍稳定返回免费层零配额，就应停止反复建 Key、重新绑定计费或无限重试，保存脱敏错误并交给 Google 支持核查。`RetryInfo` 给出几秒后重试，也不会把原本为零的适用上限变成正数。

本文依据 2026 年 10 月 5 日核对的 Google 文档和有日期的用户报告更新；没有使用真实账户进行付款、改 Key 或 API 恢复测试。下面的控制台名称来自官方文档，实际账户可能处于不同的计费计划或迁移状态。

## 先确认零的是哪项限制

保存原始错误，找出 HTTP 状态、模型、`quotaMetric`、`quotaId`、`quotaDimensions` 和错误消息中的 limit。不同 SDK、API 和版本的展示格式并不一样，不能假定每次都有同一组 JSON 字段，更不能把 `quotaValue` 一律解释成“已使用次数”。

例如，2026 年 3 月的一条[开发者论坛报告](https://discuss.ai.google.dev/t/gemini-api-gemini-2-0-flash-limit-0/129136)同时列出免费层请求、输入 token 的零限制，以及约三秒的 `RetryInfo`。这是该用户收到的错误，并非所有响应的通用模板。这里有用的判断是：错误明确指向免费层零上限时，应先核对请求归属和可用资格；如果实际限制为正、近期使用量已经达到它，才进入通常的限流恢复。

| 你现在看到的现象 | 先采取的动作 | 判断结果 |
|---|---|---|
| 运行进程的 Key 所属项目与付费项目不同 | 修改真正发请求的配置来源，重启相关进程 | 重新检查同一目标模型，不以另一个终端的成功替代 |
| 同项目显示 `Set up billing`、`Set up Prepay` 或 `No credits` | 按对应状态完成缺失设置或处理余额 | 看状态是否清除、付款是否确认，以及有效配额是否更新 |
| 计费正常，但目标模型没有免费 API 资格 | 确保请求走可用的付费项目，并核对准确模型 ID | 免费文本模型成功不能证明图片模型可调用 |
| 同项目、同模型有正配额，错误仍稳定显示免费层零限制 | 停止盲目重试，收集对应时间的证据 | 交给支持核查状态与执行结果不一致 |
| 返回正上限的 RPM、TPM、RPD 或支出限制 | 对照被耗尽的维度降载或等待相应窗口 | 不按“免费层零配额”修复，也不靠换 Key 增容 |

Gemini Developer API 的限制按项目执行，同项目多个 Key 共享配额；Key 没有独立计费设置，而是继承所属项目的计费状态。依据分别见 [Google 速率限制文档](https://ai.google.dev/gemini-api/docs/rate-limits)和[计费文档的项目与 Key 说明](https://ai.google.dev/gemini-api/docs/billing#projects-api-keys)。

## 在失败的进程里找到生效 Key

先记下失败发生在终端、VS Code、Notebook、ADK Web、容器、CI 还是线上服务，同时记录请求域名、API 版本和精确模型 ID。若请求实际发往 Vertex AI 或第三方端点，应核对那条服务的认证与计费，不能拿 AI Studio Developer API 的页面代替。

对于使用环境变量自动取 Key 的 Gemini 客户端，官方规定：`GOOGLE_API_KEY` 与 `GEMINI_API_KEY` 同时存在时，**`GOOGLE_API_KEY` 优先**。如果代码显式传入 Key，或者框架从自己的配置、`.env`、部署 secret 中取值，还要检查那个来源。仅检查环境变量，不一定能证明最终传给客户端的是什么。[Google API Key 配置说明](https://ai.google.dev/gemini-api/docs/api-key#setup-environment)

下面的 Python 代码只检查变量是否存在，不联网、不输出密钥。可以放在客户端初始化之前，观察实际应用进程的输出：

```python
import os

has_google = bool(os.environ.get("GOOGLE_API_KEY"))
has_gemini = bool(os.environ.get("GEMINI_API_KEY"))
print("GOOGLE_API_KEY 已设置:", has_google)
print("GEMINI_API_KEY 已设置:", has_gemini)

if has_google:
    print("自动读取环境变量时，优先来源是 GOOGLE_API_KEY")
elif has_gemini:
    print("自动读取环境变量时，来源是 GEMINI_API_KEY")
else:
    print("这两个变量均未设置；继续检查显式 Key 和框架配置")
```

这段代码只能证明变量来源，不能从变量名推断项目。接着在 [AI Studio API keys](https://aistudio.google.com/api-keys) 中确认所用 Key 的关联项目，记录准确的 Project ID，再到 [Projects](https://aistudio.google.com/projects) 检查这个项目。不要把 Key 贴进日志、截图或论坛；需要团队协助时，使用内部的 Key 名称和项目标识核对。

如果发现取错了 Key，只修改造成错误的那个配置来源：例如部署 secret 仍指向测试项目，或者旧 `GOOGLE_API_KEY` 覆盖了新 `GEMINI_API_KEY`。修改后重新启动实际服务；Windows 修改持久环境变量后，也要打开新终端加载。浏览器切换项目、在另一个 PowerShell 窗口临时设置变量，都不会自动更新已经运行的服务。

[LINUX DO 的一条中文讨论](https://linux.do/t/topic/1261734/1)正好说明这种差别：2025 年 12 月，发帖者报告 PowerShell 和 VS Code 的 ADK Web 使用了不同环境，重新建 Key 没有帮助；修正环境后，错误变成了 503。这个个人案例可以提示检查进程配置，却不能证明 503 就代表付费配额验证通过或内容生成成功。

## 对照项目当前状态完成计费设置

![同一项目的计费、预付、余额状态与相应核对动作](https://blog.laozhang.ai/posts/zh/paid-tier-getting-free-tier-requests-limit-0/img/project-billing-state.webp)

现在检查的是上一步确认的项目。进入 [AI Studio Projects](https://aistudio.google.com/projects)，查看它的 `Billing Tier` 和 `Status`，再到 [Billing](https://aistudio.google.com/billing) 检查所关联计费账户的计划、付款与状态。

“买了 Gemini 订阅”“绑过信用卡”“另一个项目是 Tier 1”都不能代替这一步。API Key 属于项目，项目继承关联计费账户的状态；当前预付或后付计划也会改变恢复动作。[Google 计费设置与状态说明](https://ai.google.dev/gemini-api/docs/billing)

| 项目或计费页面显示什么 | 具体修复方向 | 完成后看什么 |
|---|---|---|
| `Set up billing` | 从这个项目的按钮进入，选择或创建适用的有效计费账户并完成流程 | 该项目已关联账户，并显示实际用量层级与计划 |
| `Set up Prepay` | 完成该账户要求的 Prepay 设置，不停在“已关联计费”这一步 | 预付计划完成，必要付款正式确认 |
| `No credits` | 核对预付账户是否完成设置、可用余额是否耗尽，按账户提示处理 | 可用余额恢复且相关状态清除 |
| 付款处理中 | 检查交易是否正式确认，按当前支付方式的处理时间等待 | 付款确认后再检查项目和有效配额 |
| 账户 inactive、unsupported、逾期或付款失败 | 由账户负责人在 Cloud Billing 核对账户状态并处理对应问题 | 账户恢复可用，而不是只看 Gemini 预付余额 |
| 从 Postpay 向 Prepay 迁移时中途退出 | 返回完成该流程；若不想采用该计划，联系 Cloud Billing 支持处理 | 账户不再处于未完成、无法收费的过渡状态 |

这些状态对应的动作来自官方当前计费文档。对于要求 Prepay 的账户，文档写明最低充值为 5 美元或等值当地货币；有些账户被分配 Postpay 或仍处于迁移过程，应以自己的计划和通知为准，不要假定所有账户都必须走同一充值流程。

**预付余额归零与免费层零配额并不是同一件事。** 当前文档说明，余额归零会让该计费账户下所有关联项目的 Key 停止服务，返回 HTTP 402；项目不会自动降回 Free Tier。若收到 402，处理余额而非给请求加退避；如果报错仍是 429 免费层零限制，继续核对请求和项目状态，不凭“以前充过值”断定根因。[Prepay 说明及余额 FAQ](https://ai.google.dev/gemini-api/docs/billing#prepay)

余额为正也不保证服务可用。计费账户月度上限、项目支出上限，以及关联 Cloud 账户其他服务的逾期款项，都可能影响访问。检查当前警告和支出控制项即可，不要把提高支出上限、解绑再绑定账户当成默认修复。涉及付款或账户更改时，应由有权限的负责人根据实际需求操作。

![修正后在原失败进程验证同一模型并按实际返回处理](https://blog.laozhang.ai/posts/zh/paid-tier-getting-free-tier-requests-limit-0/img/quota-recovery-verification.webp)

## 文本能用、图片报零：检查具体模型，不直接判定 Bug

先到 [AI Studio 有效速率限制](https://aistudio.google.com/rate-limit)查看**同一项目、准确模型和调用方式**的限制，再核对[官方定价页](https://ai.google.dev/gemini-api/docs/pricing)是否提供该模型的 Free Tier。用量层级、模型资格和实际剩余额度回答的是不同问题。

截至 2026 年 10 月 5 日，官方定价页对以下图片模型的免费层输入、输出均标为 `Not available`：

- [`gemini-3.1-flash-image`](https://ai.google.dev/gemini-api/docs/pricing#gemini-3.1-flash-image)；
- [`gemini-3.1-flash-lite-image`](https://ai.google.dev/gemini-api/docs/pricing#gemini-3.1-flash-lite-image)；
- [`gemini-3-pro-image`](https://ai.google.dev/gemini-api/docs/pricing#gemini-3-pro-image)。

因此，另一个提供免费额度的文本模型能成功，并不能证明当前图片请求使用了付费项目，也不能证明图片模型获得了有效配额。要比较两个结果，必须确认它们来自相同进程、Key、项目和端点，并分别核对模型资格与限制。

同时检查是否还在调用旧模型或旧别名。Google 对 [`gemini-2.5-flash-image`](https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-flash-image)公布的停止服务计划是 2026 年 10 月 2 日，并提示迁移到 3.1 Flash Image 或 Flash Lite Image。这个日期已经过去；排查时应先按当前官方模型信息修正调用目标。公布的退役计划不是本文真实调用验证，也不能单独解释你收到的某条 429。

确实存在“文本能用、付费图片仍报零”的用户报告。例如[这条论坛讨论](https://discuss.ai.google.dev/t/429-resource-exhausted/181690)的发帖者在 2026 年 9 月 7 日报告 Tier 1、Postpay 下 Flash Lite Image 返回免费层零限制，等待后仍失败；后续回复请求项目资料调查。可见帖子没有给出确认根因或解决结果，不能由此推导成“所有付费图片请求都遇到同一个持续 Bug”。

如果项目状态正常、目标模型有正的有效配额，实际请求仍被免费层零限制拒绝，已经具备升级给支持的理由。此时不要继续根据 Key 创建时间猜测“旧 Key 缓存”：官方说明 Key 继承项目状态，并没有要求每次启用计费都必须重建 Key。

## 什么情况下值得等待，怎样确认恢复

等待必须对应一个会随时间改变的条件。当前计费文档说付款或满足升级条件后，层级通常在约十分钟内反映；速率限制文档说 Free 到 Tier 1 通常立即生效。两者都不能作为“五分钟一定恢复”的承诺。银行转账可能需要数天确认，费用图表也可能延迟到一天或更久，图表暂时没有费用并不能证明计费未关联。[计费处理时间](https://ai.google.dev/gemini-api/docs/billing#processing-times)

| 已确认的阻塞 | 等待是否有用 | 下一步 |
|---|---|---|
| 付款尚未确认、符合条件的层级更新处理中 | 有用，等待对应处理完成 | 回看交易、项目状态和有效配额 |
| 正上限的 RPM、输入 TPM 或滚动支出限制已耗尽 | 有用，但同时降低请求频率或输入规模 | 对照实际窗口，再做有次数上限的重试 |
| 正上限的 RPD 已耗尽 | 等待日配额重置可能有用 | 官方规定按太平洋时间午夜重置；零资格不会因此增加 |
| 模型不提供免费 API、Key 指错项目、Prepay 未完成 | 单纯等待无用 | 修正缺失条件后再验证 |
| HTTP 402、403，或不匹配状态下持续免费层 limit 0 | 连续退避不能解决配置、付款或权限 | 处理明确问题或停止并升级支持 |

滚动支出限制按十分钟窗口评估，是否适用于你的账户与计费历史、账户状态有关；它与月度支出上限不同。要判断具体容量，使用 [Google 当前速率限制说明](https://ai.google.dev/gemini-api/docs/rate-limits)和自己的有效限制，不复制固定 Tier RPM 或“付费每日无限”的旧表。

修正后，在原先失败的环境中，对原目标模型做一次最小、低输出请求；这可能产生费用，先确认你接受相应计费。保存请求时间、模型、项目、状态与脱敏响应。如果成功，再恢复小规模任务并观察，最后逐步恢复原负载。

成功返回内容说明那次请求可用，**不会单独证明它属于付费项目**；归属仍需与 Key、项目、计费状态和控制台记录对应。错误从零配额变成 503，只说明失败类型改变；按临时错误处理，不能宣布恢复。若已变成 403，转到[按失败动作排查 Gemini API Key 权限](https://blog.laozhang.ai/zh/posts/gemini-api-key-permission-denied)，不要继续充值。

对于确认属于暂时性 429 或 5xx 的错误，可使用有次数上限的指数退避和抖动。官方 SDK 可能已有自动重试，先核对所用版本与设置，避免在外层叠加无限循环。[Google 重试指南](https://ai.google.dev/gemini-api/docs/troubleshooting#retry-strategy)

## 状态一致仍报零，提交哪些证据

把证据对齐到同一次失败，支持才有机会判断“页面状态正确，实际执行却不一致”。准备以下资料：

- 带时区的发生时间、HTTP 状态和完整脱敏错误；
- 请求域名、API 版本、方法、精确模型 ID；
- 实际运行环境、SDK 版本、Key 配置来源与关联 Project ID；
- 同项目的 `Billing Tier`、`Status`、计费计划和付款确认状态；
- 同模型有效配额的截图或记录，以及对应时间的使用量；
- 若响应提供 request ID 或 trace ID，附上该标识；
- 每次只修改一项配置后，错误是否改变、是否成功返回内容。

付款、账户状态和迁移未完成的问题联系 [Cloud Billing 支持](https://cloud.google.com/support/billing)；无法解释的模型配额执行问题可以在 [Google AI 开发者论坛](https://discuss.ai.google.dev/)查询对应模型讨论或提交脱敏报告。项目等账户资料通过可信的私密支持渠道提供，公开帖子不要附完整 Key、账单敏感信息或用户提示词。

业务必须继续时，可以暂缓失败的图片任务，或使用团队已经验证过的其他模型、服务路线。文本模型可承接纯文本任务，却不能替代图片生成；另一条路线也有自己的费用、认证和限制，应单独验证，不能当作“自动修好这个项目”的证明。

## 常见问题

### 新建 API Key 能修复 free_tier_requests limit 0 吗？

只有它纠正了实际凭证或项目错误，才可能帮助恢复。相同项目中的新 Key 继承相同计费状态与配额，不会创建新的付费额度。若 Key 泄露、被封锁或认证限制不匹配，按那个错误处理；不要把重建 Key 当作零配额的通用开关。[Key 与项目计费关系](https://ai.google.dev/gemini-api/docs/billing#projects-api-keys)

### 我已经付费，为什么后台仍显示免费层限制？

先确认付款对应的项目就是失败 Key 的所属项目，再检查这个项目当前的计费计划和状态。付款未确认、Prepay 流程未完成、错误进程读取了另一个 Key，都需要不同动作；这些条件全部一致而仍报免费层零限制时，带证据联系支持。仅凭报错不能确认是哪一种原因。

### 按 RetryInfo 等了几秒，为什么仍然 limit 0？

重试提示不会创建模型资格或完成计费。它适用于可随时间恢复的请求条件；若适用上限仍是零，重复等待同样的秒数不会修正项目、Key 或模型资格。先完成上面的核对，只有正配额窗口耗尽或暂时服务错误，才使用有限重试。

### 同一项目多建几个 Key，能避免这类限制吗？

不能增加项目配额。Gemini Developer API 限制按项目执行；同项目不同进程、成员和 Key 的请求会共同消耗它。对于容量不足，降低并发、减少输入、等待正确窗口或申请适用配额；对于持续零配额，核对状态并升级支持。[项目级速率限制](https://ai.google.dev/gemini-api/docs/rate-limits)

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-05。

- [开发者论坛报告](https://discuss.ai.google.dev/t/gemini-api-gemini-2-0-flash-limit-0/129136) (discuss.ai.google.dev)
- [Google 速率限制文档](https://ai.google.dev/gemini-api/docs/rate-limits) (ai.google.dev)
- [计费文档的项目与 Key 说明](https://ai.google.dev/gemini-api/docs/billing) (ai.google.dev)
- [Google API Key 配置说明](https://ai.google.dev/gemini-api/docs/api-key) (ai.google.dev)
- [AI Studio API keys](https://aistudio.google.com/api-keys) (aistudio.google.com)
- [Projects](https://aistudio.google.com/projects) (aistudio.google.com)
- [LINUX DO 的一条中文讨论](https://linux.do/t/topic/1261734/1) (linux.do)
- [Billing](https://aistudio.google.com/billing) (aistudio.google.com)
- [AI Studio 有效速率限制](https://aistudio.google.com/rate-limit) (aistudio.google.com)
- [官方定价页](https://ai.google.dev/gemini-api/docs/pricing) (ai.google.dev)
- [这条论坛讨论](https://discuss.ai.google.dev/t/429-resource-exhausted/181690) (discuss.ai.google.dev)
- [Google 重试指南](https://ai.google.dev/gemini-api/docs/troubleshooting) (ai.google.dev)
- [Cloud Billing 支持](https://cloud.google.com/support/billing) (cloud.google.com)
- [Google AI 开发者论坛](https://discuss.ai.google.dev/) (discuss.ai.google.dev)