# Nano Banana API 报错：先分清 429、503、无图像和请求被拒

> 把 Nano Banana API 故障先拆成 429、503/504、无图像和请求被拒四条路线，再决定退避、排队、修 payload、修权限还是转到更精确的错误页。

- URL: https://blog.laozhang.ai/zh/posts/nano-banana-pro-error
- Published: 2026-02-22
- Updated: 2026-04-19
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: AI 图像生成
- Tags: Nano Banana API, Gemini API, API 排错, 429, 503, 无图像, 请求被拒

---
Nano Banana API 出错时，第一步不是重试、换 key、换模型或换供应商，而是先把故障分支分清。`429 RESOURCE_EXHAUSTED` 指向项目或模型的配额压力；`503 UNAVAILABLE` 先按容量不可用处理；`504 DEADLINE_EXCEEDED` 是超时分支；成功响应却没有图像时，要检查 `parts`、`inlineData`、输出模态、安全结束原因和文件引用；“请求被拒”还要拆成权限、密钥、项目、文件资源、安全策略或网关拒绝。

| 看到的现象 | 第一项安全检查 | 下一步 |
| --- | --- | --- |
| `429 RESOURCE_EXHAUSTED` | 查当前项目和模型的实际限制，不先轮换同项目 key。 | 有边界退避，把非实时任务排队或转到 429 专门路线。 |
| `503 UNAVAILABLE` / `504 DEADLINE_EXCEEDED` | 保持同模型、同端点、同项目、同 payload 复测一次。 | 503 走容量退避或排队；504 优先修超时和请求负载。 |
| 无图像或只有文本 | 遍历 response `parts`，确认是否有真实图像 part。 | 修 parser、输出模态、安全结果或文件资源。 |
| 请求被拒 | 区分 `403 PERMISSION_DENIED`、安全结束、文件不可访问和网关策略。 | 修对应 owner，不把所有凭据同时换掉。 |

证据边界：Google Gemini API 的排错、图片生成、rate limits、Batch API 和 Files API 文档已在 2026-04-19 复核。过期配额表、固定低峰时段、错误率百分比和“必然修好”的说法不进入正文判断。

## 429 RESOURCE_EXHAUSTED 先按配额处理

![429、503 和 504 的 Nano Banana API 状态分支图](https://blog.laozhang.ai/posts/zh/nano-banana-pro-error/img/status-split.webp)

`429 RESOURCE_EXHAUSTED` 是配额或速率限制信号，先不要把它解释成模型坏了、key 坏了或服务整体不可用。Google 的 Gemini API 排错文档把 `RESOURCE_EXHAUSTED` 放在 rate limit 路线，rate limits 文档又明确指出限制通常按项目维度生效，所以同一个项目下轮换多个 API key 未必改变结果。

先查当前项目、当前模型、当前付费层级的实际限制。图片模型、预览模型和付费层级的限制会变，旧表格不适合作为生产逻辑。确认分支以后，再用带 jitter 的指数退避，并给重试设置上限。非实时图片任务不要和用户同步请求抢同一段配额，适合进入队列或批处理。

如果每次正常使用都会撞到 429，问题已经不是“再等几秒”，而是容量规划。更细的配额处理可转到 [Gemini Image 429 rate limit 排查](https://blog.laozhang.ai/zh/posts/gemini-image-429-rate-limit)；如果要重新设计项目级限额和队列，可看 [Gemini API rate limits 架构](https://blog.laozhang.ai/zh/posts/gemini-api-rate-limits-guide)。

## 503 和 504 不要混在一起修

`503 UNAVAILABLE` 是临时不可用或容量压力，不能直接推导为 key 错、账单错或 prompt 错。最干净的动作是保持同路径复测：同模型、同端点、同项目、同 key、同 payload、同输入文件。如果第二次仍是 503，才继续容量分支；如果变成 429，就切到配额；如果变成结构化客户端错误，就停止按过载处理。

`504 DEADLINE_EXCEEDED` 的 owner 不同。它说明请求超出时间预算，常见修法是提高客户端 timeout、降低输入复杂度、减少一次请求内的图像或上下文负载。把 504 当作 503 反复重试，只会浪费队列时间。

生产处理顺序应当是：确认 code 和 status；同路径有限重试；504 修 timeout 或减负载；持续 503 时暂停同步重试、排队或转到 [Gemini 3 Pro Image 503/504 专门路线](https://blog.laozhang.ai/zh/posts/fix-gemini-3-pro-image-503-overloaded)。

## 无图像或只有文本时先查响应结构

![Nano Banana API 无图像响应的解析检查板](https://blog.laozhang.ai/posts/zh/nano-banana-pro-error/img/no-image-parser.webp)

HTTP 成功不等于拿到了图片。图片通常在 response `parts` 里的图像数据中，应用代码如果只读第一段文本、只看顶层字段，或者没有请求图像输出，就会把成功响应误判成“No Image”。

先遍历所有 candidate 和 part，查 `inlineData`、MIME type、输出模态和 finish reason。没有图像 part 时，再看请求是否真的要求 image output，是否被 safety finish 截断，输入文件是否是 API 可访问的资源，而不是本地路径或另一个项目的旧 URI。

修法通常很小：明确请求图像输出，保存真实的 image part，记录文本 part 和 safety 信息，修正文件上传和引用。不要在 parser 还没确认之前宣布 Nano Banana API 宕机。

## 请求被拒不是单一错误

“请求被拒”只是外层症状。真正 owner 可能是 `403 PERMISSION_DENIED`、无效或被封的 key、项目没有启用 API、安全策略、文件资源不可访问，或者中转网关自己的策略。

先看 HTTP 层。如果是 403，检查 key 是否有效、项目是否启用 Gemini API、key 是否暴露后被撤销、请求是否走了预期项目。再看生成层：`finishReason: SAFETY` 是安全分支，不能和 403 混在一起。然后看文件层：API 需要能访问上传后的文件资源，不能只传本地路径。最后看网关层：Google 返回的 status 和网关返回的 status 要分开记录。

只有 owner 清楚，动作才会准确。权限问题修项目和 key；安全问题改 prompt 或路线；文件问题修上传和资源引用；网关问题找网关鉴权或策略。

## 同路径复测能保住诊断信号

![Nano Banana API 同路径复测工作流](https://blog.laozhang.ai/posts/zh/nano-banana-pro-error/img/same-path-verification.webp)

同路径复测的目标不是拖慢排查，而是防止一次失败被五个改动污染。复测前保持模型、端点、项目、key、payload、输入资产和请求格式不变，再观察分支是否稳定。

| 复测结果 | 说明 | 动作 |
| --- | --- | --- |
| 仍然 429 | 配额分支稳定 | 退避、排队、批处理或走 429 专门路线 |
| 仍然 503 | 容量分支稳定 | 有边界重试、排队或走 503 专门路线 |
| 变成 504 | 超时分支显露 | 提高 timeout 或降低请求复杂度 |
| 成功但无图像 | 响应结构分支显露 | 查 parts、inlineData、模态、安全和文件 |
| 变成 403/拒绝 | 权限、安全或文件分支显露 | 修对应 owner |

分支证明以后，每次只改一个变量。换模型就别同时换 key；换 key 就别同时改 payload；换输入文件就别同时换端点。持续配额压力可以再看 [Nano Banana 2 alternative 429 路线](https://blog.laozhang.ai/zh/posts/nano-banana-2-alternative-429)；非实时任务也可以考虑 Google 的 Batch API。

## 常见问题

### 看到 503 就说明 Nano Banana API 宕机吗？

不一定。一次 `503 UNAVAILABLE` 只能说明当前请求进入可用性或容量分支。先同路径复测，再看其他模型或端点是否同样失败。

### 开通付费能修好 503 吗？

付费层级可能影响 429 配额，但不自动修复已经证明的 503 容量分支。429 和 503 要分开处理。

### 为什么返回了文本但没有图片？

常见原因是 parser 没找到 image part、请求没有要求图像输出、生成被 safety 结束，或输入文件不是 API 可访问资源。先查 `parts` 和 `inlineData`。

### Request Denied 该先查哪里？

先看 HTTP status。如果是 403，查 key、项目、API 启用和权限；如果 HTTP 成功但 finish reason 是 safety，按安全分支处理；如果涉及输入文件，查资源 URI 和项目所有权。

### 什么时候才该换模型或换路线？

分支证明以后再换。持续 429、持续 503、明确安全限制或文件/网关策略都可能需要换路线，但不要在第一轮就同时更换模型、端点、key、prompt 和输入文件。