修复 Gemini 图像生成错误：429、402 等错误码对照与重试规则

截至 2026 年 10 月 5 日，Gemini 生图失败，先分清是在应用里还是在 API 里。

• 在 Gemini 应用里（网页版或手机 App）点了生成却没有图：通常没有错误码，问题多半出在登录、年龄、额度或内容政策上，看下一节逐条对照。
• 用 API 或 AI Studio 的 key 写代码：看返回的 HTTP 状态和错误码。429、500、503、504 属于暂时性错误，按指数退避重试；400、401、402、403、404 是请求、账户、权限或模型 ID 本身的问题，重发多少次结果都一样，要先改掉原因。

下面的错误码、重试规则和参数要求都来自 Google 的 API errors 与 Troubleshooting guide 页面。

在 Gemini 应用里生不出图：六种情况和下一步

应用里的失败大多只有一句提示，按情况对号入座即可。以下规则来自 Google 的 Gemini 应用帮助中心（生成和编辑图片、使用限额）。

1. 没有登录：生成图片必须登录 Google 账号，先登录再试。
2. 年龄不够：个人账号满 13 岁（或所在地规定年龄）才能生成图片，满 18 岁才能编辑图片，未满 18 岁时上传照片让 Gemini 修改会被拒绝。
3. 地区、语言或账号类型不在支持范围：图片功能只在 Gemini 应用支持的国家和语言里提供；工作或学校账号可能另有条款和限制。Gemini API 与 Google AI Studio 的可用地区名单里没有中国大陆和香港，这是服务范围的限制，改请求参数解决不了。
4. 额度用完：Gemini 应用按计算量计限额，每 5 小时刷新一次，直到当周上限；AI Plus 是标准额度的 2 倍，AI Pro 是 4 倍，AI Ultra 是 AI Pro 的 5 倍或 20 倍。Nano Banana 2 当日额度用完后，“用 Pro 重做”也不能再用。具体能出多少张见 Gemini 免费生图次数限制。
5. 人物或安全原因被拒：这是 Google 生成式 AI 使用政策下的判定，不是故障。未经同意使用他人肖像、侵犯隐私、未经同意的亲密影像等请求会被拒，系统判定可能违规的图片也可能被移除；确认违规会收到应用内或邮件通知，多次违规可能被限制使用生成式 AI 功能乃至 Google 账号。怎么判断是政策、账号条件还是额度，见 Gemini 为什么限制生成人物图片。
6. 一直转圈、图片不显示或加载失败：这类前端和服务状态问题按 Nano Banana 无法生成图片的 12 个修复分支逐项排查；提示“需求量大”时先看 Gemini 高需求错误。

Gemini API 错误码对照表：含义、怎么改、能不能重试

下表的错误码是 Interactions API 返回的 error.code。用 generateContent 时 HTTP 状态码相同，错误体里给的是大写状态名，例如 429 对应 RESOURCE_EXHAUSTED、503 对应 UNAVAILABLE、参数错误的 400 常见 INVALID_ARGUMENT。写重试逻辑时按 HTTP 状态码判断，两套接口都适用。

表里有几处最容易判断错：

• 402 和 failed_precondition 都跟钱有关，处理方式不同。付费层要绑定结算账号并至少预充 $5，2026 年 3 月 23 日起新用户默认是预付费；余额归零后请求一律返回 402，Google 写明“不要重试”，充值或开启自动充值后才会恢复（Billing）。failed_precondition 则是计费这个前提没满足，比如项目根本没启用计费。
• 404 model_not_found 多半是代码里还写着已停用的模型 ID。图片模型的 -preview ID 到 2026 年 6 月 25 日已全部停用，旧教程里的写法都会落到这里，换成现役 ID 即可。
• 429 有三个 code，quota_exceeded 等几分钟也没用。rate_limit_exceeded 和 too_many_requests 按指数退避重试即可；quota_exceeded 是当日配额用完，每日请求数在太平洋时间午夜重置，当天反复重试只会继续拿到 429。
• key 泄露会被直接封禁。Google 会屏蔽已知公开泄露的 key，报错信息是 Your API key was reported as leaked. Please use another API key.，只能在 AI Studio 新建 key。

Nano Banana Pro 各类报错的汇总入口见 Nano Banana Pro 错误排查中心。

被拦截或没有图片：image_safety、image_other 与 no_image

请求到达了模型、却拿不到图片时，Google 把原因分成两类：生成被拦截（安全、政策或内容限制），和生成出错（输出结构有问题）。在 Interactions API 里它们以下面的 code 返回；在 generateContent 里，原因写在响应的 candidates[].finishReason 或 promptFeedback.blockReason 字段里，只有缺少思考签名会直接返回 400。

对被拦截的这几类，Google 的建议是修改输入后再试，原样重发结果不会变。另外三点会影响判断：

• 把 safetySettings 调成 BLOCK_NONE 或 OFF 通常没用。对当前的 Gemini 模型，可调的几个过滤类别默认已经是关闭状态，所以 IMAGE_SAFETY、PROHIBITED_CONTENT、OTHER 这类结果基本不来自可调过滤器（这是根据默认值做的推断，Google 没有逐条说明）；儿童安全等核心保护始终生效、不能调整；Interactions API 不支持自定义安全设置。哪些能调、哪些不能，见 Nano Banana Pro 安全过滤器。
• 试图绕过安全过滤本身就违反 Google 的生成式 AI 禁止使用政策，可能招致账号层面的处理。
• Gemini 图片模型没有“允许生成人物”的开关。Imagen 的 personGeneration 参数随 Imagen 4 系列在 2026 年 8 月 17 日停用一起消失了，人物相关的拦截同样以上表的 finishReason 或 blockReason 出现。

思考签名的报错在 generateContent 里表现为 400。Vercel AI SDK 的 issue #12988 记录过一例：Nano Banana 2 生成图片后，第二轮编辑因为 SDK 回传上一张图时丢了签名，返回 400 INVALID_ARGUMENT，信息为 Image part is missing a thought_signature，该 SDK 在 ai 6.0.114 中修复。

哪些错误该重试：Google 的退避规则与 SDK 重试开关

Google 的规则很明确：只重试暂时性错误（429、408 和 5xx），不重试 400、402、403 这类客户端错误，因为它们代表 key 无效、预付费余额用完或请求写错。重试时：

1. 指数退避：第一次等约 1 秒，之后 2 秒、4 秒、8 秒依次翻倍。
2. 加随机抖动：让大量客户端不在同一时刻一起重试。
3. 设最大重试次数：避免无限循环。

Google 的排错指南写着官方 SDK 默认自带这套重试，Python SDK 会自动重试最多 4 次，初始间隔约 1 秒，最长 60 秒。但 2026 年 10 月 5 日用 google-genai 2.28.0 对一个固定返回 429 的本地服务器测试，结果不同：默认的 genai.Client() 只发 1 次请求就抛出 APIError，不会重试。这是 client.models.generate_content 的结果；同版本的 client.interactions.create 不一样，默认会自己重试 429（同一测试里约 3 秒内发了 4 次）。要让它重试，需要在创建客户端时显式开启 HttpRetryOptions：

from google import genai
from google.genai import types

client = genai.Client(http_options=types.HttpOptions(retry_options=types.HttpRetryOptions()))

开启后同样的测试共发出 5 次请求（1 次原请求加 4 次重试），间隔从约 1 秒起指数增长、最长 60 秒，会重试的状态码包括 408、429、500、502、503、504。JS、Go、Java SDK 没有做同样的测试，默认行为以实际版本为准。

SDK 重试和自己写的重试循环二选一，不要叠加：开了 HttpRetryOptions 还在外面套一层最多 5 次的循环，每次 SDK 内部又最多发 5 次，一个失败请求最多会发出 25 次。

直接调 REST，或用 SDK 但想按错误码自己决定重不重试（保持 SDK 默认的不重试）时，可以用下面这段判断逻辑。它只负责“该不该重试、等多久”，不发请求，用 Python 3 可以直接运行：

import random

# 这些 code 即使状态码看起来可重试，也不该原样重发
NO_RETRY_CODES = {"quota_exceeded", "payment_required", "unimplemented"}


def should_retry(http_status: int, error_code: str = "") -> bool:
    if error_code in NO_RETRY_CODES:
        return False
    if http_status in (408, 429):
        return True
    return 500 <= http_status < 600 and http_status != 501


def backoff_seconds(attempt: int, base: float = 1.0, cap: float = 60.0) -> float:
    # 1、2、4、8 秒……封顶 60 秒，再加最多 1 秒随机抖动
    return min(cap, base * 2 ** attempt) + random.uniform(0, 1)

用 generateContent 时拿不到 Interactions 的小写 code，error_code 留空，只按状态码判断即可；这时日配额耗尽的 429 也会被当作可重试，所以调用方一定要设最大重试次数，例如 5 次。501 unimplemented 表示功能不支持，Google 的建议是换用支持的功能，所以排除在外。

还有一条跟成本有关：返回 400 或 500 的失败请求不收 token 费用，但仍然计入配额（Billing）。盲目重试不花钱，却会更快耗尽配额。

429 RESOURCE_EXHAUSTED 的四种来源：速率、日配额、消费上限、免费层

图片请求的 429 不全是“请求太快”。按 Google 的 速率限制 页面，可以分成四种：

1. 每分钟速率超限（rate_limit_exceeded）：图片模型除了每分钟请求数，还有每分钟图片数（IPM）。现役图片模型的具体数值只在 AI Studio 里按项目显示。限额按项目计算、不按 key 计算，同一个项目里多建几个 key 不会多出额度。
2. 当日配额用完（quota_exceeded）：太平洋时间午夜重置，或者申请提额。
3. 消费速率上限：按滚动 10 分钟计，Tier 1 为 $10，Tier 2 为 $50，Tier 3 为 $200，超出返回 429 RESOURCE_EXHAUSTED；是否适用取决于账单历史和账户状态。按 Google 的价格表换算，Tier 1 的 $10 大约够 74 张 Nano Banana Pro 的 1K 或 2K 图（每张 1,120 个图片 token × $120/百万 = $0.1344），或约 148 张 Nano Banana 2 的 1K 图（每张 1,120 × $60/百万 = $0.0672）。适用消费上限的项目，批量任务在 10 分钟内超过这个量就会撞上限。
4. 免费层项目调用图片模型：所有现役 Gemini 图片模型的图片输出都没有免费层，免费层项目的生图请求会因配额失败，报错里常见 free_tier_requests 和 limit: 0（这串文字来自开发者反馈，Google 文档里没有原文）。已经付费还这样报，按 已付费仍报 free_tier_requests limit 0 排查。

再往下深挖：图片 429 的整体处理见 Gemini 图片生成 429 速率限制，Nano Banana Pro 的 RESOURCE_EXHAUSTED 与任务恢复代码见 Nano Banana Pro RESOURCE_EXHAUSTED 429。503 和 429 看起来都像“服务忙”，但 503 是 Google 那边过载，处理思路见 Nano Banana Pro 报 503。

请求参数检查清单：现役模型 ID、尺寸大写 K、/v1beta

400 和 404 多半出在请求本身。发请求前按这几项过一遍。

1. 模型 ID 用现役的。下表来自 Google 的 弃用时间表，旧 ID 现在会返回 404 model_not_found：

2. 尺寸写大写 K。可选值是 512、1K、2K、4K，默认 1K；写成小写 1k 会被拒绝。512 只有 Nano Banana 2 支持，Nano Banana 2 Lite 只支持 1K。

3. 字段放进对应的接口。Interactions API 用 response_format（"type": "image" 加 image_size、aspect_ratio）；generateContent 用 generationConfig.imageConfig.imageSize 和 aspectRatio。把一套接口的字段发给另一套，多出来的字段会被当作不认识的参数，触发 parameter_unknown。

4. 用 /v1beta 路径。Google 的图片示例走 /v1beta/interactions，generateContent 走 /v1beta/models/gemini-3.1-flash-image:generateContent 这样的路径；Beta 阶段的功能只在 /v1beta 下提供。

5. 其他参数在范围内。candidateCount 为 1 到 8 的整数，temperature 和 topP 为 0.0 到 1.0；不过 Google 建议 Gemini 3.x 模型保持默认值，调低 temperature 可能导致循环输出或质量下降。

6. SDK 用新的 google-genai。当前文档用 from google import genai，旧包 google-generativeai 和 genai.GenerativeModel 写法已不在文档中。完整的调用代码见 Gemini 图片 API 调用教程。

7. 504 先查超时设置。Gemini 3.x 模型默认开启思考，延迟和 token 用量会因此升高；客户端超时设得太短就会频繁拿到 deadline_exceeded，先去掉或调大客户端超时。

报错扣费吗、换 key 有用吗、网页版为何说不能生成图像

Gemini API 报错的请求会扣费吗？

返回 400 或 500 的失败请求不收 token 费用，但仍然计入配额。402 则说明预付费余额已经是 $0，充值前所有请求都会失败。

换一个 API key 能解决 429 吗？

同一个项目里换 key 没用，速率限制按项目计算，不按 key 计算。消费上限看的是结算账号对应的用量层级，日配额在太平洋时间午夜重置。

Gemini 网页版说“不能生成图像”是怎么回事？

网页版没有错误码，先对照上面应用一节的六种情况：登录、年龄、地区与账号类型、额度、政策拒绝、加载问题。涉及真人或他人照片的请求被拒属于政策判定；刻意改写提示词去绕过安全限制，本身就违反 Google 的使用政策。