# 修复 Gemini 图像生成错误：429、402 等错误码对照与重试规则 > Gemini 生图报错先看错误码：429 和 5xx 可退避重试，400、402、403、404 重试无效，要改请求、充值或换现役模型 ID；应用里出错先查登录、年龄与额度。 - URL: https://blog.laozhang.ai/zh/posts/gemini-image-common-errors-fix - Published: 2026-03-16 - Updated: 2026-10-05 - Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about) - Topic: 故障排查 - Tags: Gemini API, 图像生成, 错误码, 429错误, Nano Banana --- 截至 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](https://ai.google.dev/gemini-api/docs/api-errors) 与 [Troubleshooting guide](https://ai.google.dev/gemini-api/docs/troubleshooting) 页面。 ## 在 Gemini 应用里生不出图：六种情况和下一步 应用里的失败大多只有一句提示，按情况对号入座即可。以下规则来自 Google 的 Gemini 应用帮助中心（[生成和编辑图片](https://support.google.com/gemini/answer/14286560)、[使用限额](https://support.google.com/gemini/answer/16275805)）。 1. **没有登录**：生成图片必须登录 Google 账号，先登录再试。 2. **年龄不够**：个人账号满 13 岁（或所在地规定年龄）才能生成图片，满 18 岁才能编辑图片，未满 18 岁时上传照片让 Gemini 修改会被拒绝。 3. **地区、语言或账号类型不在支持范围**：图片功能只在 Gemini 应用支持的国家和语言里提供；工作或学校账号可能另有条款和限制。Gemini API 与 Google AI Studio 的[可用地区名单](https://ai.google.dev/gemini-api/docs/available-regions)里没有中国大陆和香港，这是服务范围的限制，改请求参数解决不了。 4. **额度用完**：Gemini 应用按计算量计限额，每 5 小时刷新一次，直到当周上限；AI Plus 是标准额度的 2 倍，AI Pro 是 4 倍，AI Ultra 是 AI Pro 的 5 倍或 20 倍。Nano Banana 2 当日额度用完后，“用 Pro 重做”也不能再用。具体能出多少张见 [Gemini 免费生图次数限制](https://blog.laozhang.ai/zh/posts/gemini-image-generation-free-limit-2026)。 5. **人物或安全原因被拒**：这是 Google 生成式 AI 使用政策下的判定，不是故障。未经同意使用他人肖像、侵犯隐私、未经同意的亲密影像等请求会被拒，系统判定可能违规的图片也可能被移除；确认违规会收到应用内或邮件通知，多次违规可能被限制使用生成式 AI 功能乃至 Google 账号。怎么判断是政策、账号条件还是额度，见 [Gemini 为什么限制生成人物图片](https://blog.laozhang.ai/zh/posts/gemini-image-generation-people-restriction)。 6. **一直转圈、图片不显示或加载失败**：这类前端和服务状态问题按 [Nano Banana 无法生成图片的 12 个修复分支](https://blog.laozhang.ai/zh/posts/nano-banana-not-working-gemini-image-errors)逐项排查；提示“需求量大”时先看 [Gemini 高需求错误](https://blog.laozhang.ai/zh/posts/gemini-high-demand-error)。 ## Gemini API 错误码对照表：含义、怎么改、能不能重试 下表的错误码是 Interactions API 返回的 `error.code`。用 generateContent 时 HTTP 状态码相同，错误体里给的是大写状态名，例如 429 对应 `RESOURCE_EXHAUSTED`、503 对应 `UNAVAILABLE`、参数错误的 400 常见 `INVALID_ARGUMENT`。写重试逻辑时按 HTTP 状态码判断，两套接口都适用。 | 错误码 | HTTP | 含义 | 怎么做 | 能否重试 | |---|---|---|---|---| | `invalid_request` | 400 | 请求体格式错误或参数值非法 | 对照 API 参考检查字段名和取值 | 否 | | `parameter_unknown` | 400 | 请求里有不认识的参数 | 删掉该参数后再发 | 改完再发 | | `failed_precondition` | 400 | 前置条件不满足，例如项目没启用计费 | 检查项目的计费状态和账户条件 | 否 | | `authentication` | 401 | API key 缺失、无效或过期 | 检查 key 是否填对、是否仍有效 | 否 | | `payment_required` | 402 | 预付费余额已用完 | 充值或打开自动充值 | 否，充值前不会成功 | | `permission_denied` | 403 | key 没有访问该资源的权限 | 检查 key 的权限和所属项目 | 否 | | `model_not_found` | 404 | 找不到指定模型 | 改成现役模型 ID，见下文清单 | 否 | | `rate_limit_exceeded` | 429 | 超过每分钟或每秒的请求数、token 数限制 | 等待后按指数退避重试 | 是 | | `quota_exceeded` | 429 | 当日配额用完 | 等配额重置或申请提额 | 当天重试无效 | | `too_many_requests` | 429 | 短时间内请求过多 | 等待后按指数退避重试 | 是 | | `api_error` | 500 | 服务器端意外错误 | 重试，持续出现就联系支持 | 是 | | `service_unavailable` | 503 | 服务暂时过载或宕机 | 等待后按指数退避重试 | 是 | | `deadline_exceeded` | 504 | 请求没有在截止时间内完成 | 去掉或调大客户端超时，使用服务器默认值 | 调整后可重试 | 表里有几处最容易判断错： - **402 和 `failed_precondition` 都跟钱有关，处理方式不同**。付费层要绑定结算账号并至少预充 $5，2026 年 3 月 23 日起新用户默认是预付费；余额归零后请求一律返回 402，Google 写明“不要重试”，充值或开启自动充值后才会恢复（[Billing](https://ai.google.dev/gemini-api/docs/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 错误排查中心](https://blog.laozhang.ai/zh/posts/nano-banana-pro-errors-troubleshooting-hub)。 ## 被拦截或没有图片：image_safety、image_other 与 no_image 请求到达了模型、却拿不到图片时，Google 把原因分成两类：生成被拦截（安全、政策或内容限制），和生成出错（输出结构有问题）。在 Interactions API 里它们以下面的 code 返回；在 generateContent 里，原因写在响应的 `candidates[].finishReason` 或 `promptFeedback.blockReason` 字段里，只有缺少思考签名会直接返回 400。 | Interactions 错误码 | generateContent 里看哪个值 | 含义 | 下一步 | |---|---|---|---| | `image_safety` | `IMAGE_SAFETY` | 生成的图片违反安全规则 | 修改请求内容 | | `image_prohibited_content` | `IMAGE_PROHIBITED_CONTENT` | 触及禁止内容准则 | 修改请求内容 | | `image_recitation` | `IMAGE_RECITATION` | 与受版权保护或已有内容过于相似 | 让描述和参考素材更具体、更独特 | | `image_other` | `IMAGE_OTHER`；提示词阶段为 blockReason `OTHER` | Google 只写“未说明的原因” | 见 [blockReason OTHER 该查什么](https://blog.laozhang.ai/zh/posts/nano-banana-2-blockreason-other) | | `spii` | `SPII` | 涉及敏感个人身份信息 | 去掉相关内容 | | `no_image` | `NO_IMAGE` | 应该出图但没有生成 | 见 [Nano Banana API 不出图](https://blog.laozhang.ai/zh/posts/nano-banana-2-200-ok-no-image) | | `missing_thought_signature` | 多轮请求返回 400 | 回传的历史里缺少思考签名 | 原样回传上一轮的签名，见 [Thought Signature 错误](https://blog.laozhang.ai/zh/posts/nano-banana-2-thought-signature-error) | 对被拦截的这几类，Google 的建议是修改输入后再试，原样重发结果不会变。另外三点会影响判断： - **把 safetySettings 调成 `BLOCK_NONE` 或 `OFF` 通常没用**。对当前的 Gemini 模型，可调的几个过滤类别默认已经是关闭状态，所以 `IMAGE_SAFETY`、`PROHIBITED_CONTENT`、`OTHER` 这类结果基本不来自可调过滤器（这是根据默认值做的推断，Google 没有逐条说明）；儿童安全等核心保护始终生效、不能调整；Interactions API 不支持自定义安全设置。哪些能调、哪些不能，见 [Nano Banana Pro 安全过滤器](https://blog.laozhang.ai/zh/posts/nano-banana-pro-safety-filters)。 - **试图绕过安全过滤本身就违反 Google 的生成式 AI 禁止使用政策**，可能招致账号层面的处理。 - **Gemini 图片模型没有“允许生成人物”的开关**。Imagen 的 `personGeneration` 参数随 Imagen 4 系列在 2026 年 8 月 17 日停用一起消失了，人物相关的拦截同样以上表的 finishReason 或 blockReason 出现。 思考签名的报错在 generateContent 里表现为 400。Vercel AI SDK 的 [issue #12988](https://github.com/vercel/ai/issues/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`： ```python 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 可以直接运行： ```python 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](https://ai.google.dev/gemini-api/docs/billing)）。盲目重试不花钱，却会更快耗尽配额。 ![按HTTP状态和原因区分可退避错误与必须先修复的请求错误](https://blog.laozhang.ai/posts/zh/gemini-image-common-errors-fix/img/content-3.webp) ## 429 RESOURCE_EXHAUSTED 的四种来源：速率、日配额、消费上限、免费层 图片请求的 429 不全是“请求太快”。按 Google 的 [速率限制](https://ai.google.dev/gemini-api/docs/rate-limits) 页面，可以分成四种： 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](https://blog.laozhang.ai/zh/posts/paid-tier-getting-free-tier-requests-limit-0) 排查。 再往下深挖：图片 429 的整体处理见 [Gemini 图片生成 429 速率限制](https://blog.laozhang.ai/zh/posts/gemini-image-429-rate-limit)，Nano Banana Pro 的 `RESOURCE_EXHAUSTED` 与任务恢复代码见 [Nano Banana Pro RESOURCE_EXHAUSTED 429](https://blog.laozhang.ai/zh/posts/resource-exhausted-error-nano-banana)。503 和 429 看起来都像“服务忙”，但 503 是 Google 那边过载，处理思路见 [Nano Banana Pro 报 503](https://blog.laozhang.ai/zh/posts/fix-gemini-3-pro-image-503-overloaded)。 ![Gemini图片API四类429原因与各自处理方式](https://blog.laozhang.ai/posts/zh/gemini-image-common-errors-fix/img/content-1.webp) ## 请求参数检查清单：现役模型 ID、尺寸大写 K、/v1beta 400 和 404 多半出在请求本身。发请求前按这几项过一遍。 **1. 模型 ID 用现役的**。下表来自 Google 的 [弃用时间表](https://ai.google.dev/gemini-api/docs/deprecations)，旧 ID 现在会返回 404 `model_not_found`： | 模型 | 现在该用的 ID | 已停用的旧 ID | |---|---|---| | Nano Banana 2 | `gemini-3.1-flash-image` | `gemini-3.1-flash-image-preview`（2026 年 6 月 25 日停用） | | Nano Banana Pro | `gemini-3-pro-image` | `gemini-3-pro-image-preview`（2026 年 6 月 25 日停用） | | Nano Banana 2 Lite | `gemini-3.1-flash-lite-image` | 无 | | 初代 Nano Banana | 改用 `gemini-3.1-flash-image` | `gemini-2.5-flash-image`（2026 年 10 月 2 日停用） | | Imagen 4 系列 | 改用 `gemini-3.1-flash-image` | `imagen-4.0-generate-001` 等（2026 年 8 月 17 日停用） | **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 调用教程](https://blog.laozhang.ai/zh/posts/gemini-image-api-guide-2026)。 **7. 504 先查超时设置**。Gemini 3.x 模型默认开启思考，延迟和 token 用量会因此升高；客户端超时设得太短就会频繁拿到 `deadline_exceeded`，先去掉或调大客户端超时。 ## 报错扣费吗、换 key 有用吗、网页版为何说不能生成图像 ### Gemini API 报错的请求会扣费吗？ 返回 400 或 500 的失败请求不收 token 费用，但仍然计入配额。402 则说明预付费余额已经是 $0，充值前所有请求都会失败。 ### 换一个 API key 能解决 429 吗？ 同一个项目里换 key 没用，速率限制按项目计算，不按 key 计算。消费上限看的是结算账号对应的用量层级，日配额在太平洋时间午夜重置。 ### Gemini 网页版说“不能生成图像”是怎么回事？ 网页版没有错误码，先对照上面应用一节的六种情况：登录、年龄、地区与账号类型、额度、政策拒绝、加载问题。涉及真人或他人照片的请求被拒属于政策判定；刻意改写提示词去绕过安全限制，本身就违反 Google 的使用政策。 ## 参考来源 本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-05。 - [API errors](https://ai.google.dev/gemini-api/docs/api-errors) (ai.google.dev) - [Troubleshooting guide](https://ai.google.dev/gemini-api/docs/troubleshooting) (ai.google.dev) - [生成和编辑图片](https://support.google.com/gemini/answer/14286560) (support.google.com) - [使用限额](https://support.google.com/gemini/answer/16275805) (support.google.com) - [可用地区名单](https://ai.google.dev/gemini-api/docs/available-regions) (ai.google.dev) - [Billing](https://ai.google.dev/gemini-api/docs/billing) (ai.google.dev) - [issue #12988](https://github.com/vercel/ai/issues/12988) (github.com) - [速率限制](https://ai.google.dev/gemini-api/docs/rate-limits) (ai.google.dev) - [弃用时间表](https://ai.google.dev/gemini-api/docs/deprecations) (ai.google.dev)