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 RESOURCE_EXHAUSTED 是配额或速率限制信号，先不要把它解释成模型坏了、key 坏了或服务整体不可用。Google 的 Gemini API 排错文档把 RESOURCE_EXHAUSTED 放在 rate limit 路线，rate limits 文档又明确指出限制通常按项目维度生效，所以同一个项目下轮换多个 API key 未必改变结果。
先查当前项目、当前模型、当前付费层级的实际限制。图片模型、预览模型和付费层级的限制会变，旧表格不适合作为生产逻辑。确认分支以后，再用带 jitter 的指数退避，并给重试设置上限。非实时图片任务不要和用户同步请求抢同一段配额，适合进入队列或批处理。
如果每次正常使用都会撞到 429，问题已经不是“再等几秒”，而是容量规划。更细的配额处理可转到 Gemini Image 429 rate limit 排查；如果要重新设计项目级限额和队列，可看 Gemini API rate limits 架构。
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 专门路线。
无图像或只有文本时先查响应结构
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 或路线；文件问题修上传和资源引用；网关问题找网关鉴权或策略。
同路径复测能保住诊断信号
同路径复测的目标不是拖慢排查，而是防止一次失败被五个改动污染。复测前保持模型、端点、项目、key、payload、输入资产和请求格式不变，再观察分支是否稳定。
| 复测结果 | 说明 | 动作 |
|---|---|---|
| 仍然 429 | 配额分支稳定 | 退避、排队、批处理或走 429 专门路线 |
| 仍然 503 | 容量分支稳定 | 有边界重试、排队或走 503 专门路线 |
| 变成 504 | 超时分支显露 | 提高 timeout 或降低请求复杂度 |
| 成功但无图像 | 响应结构分支显露 | 查 parts、inlineData、模态、安全和文件 |
| 变成 403/拒绝 | 权限、安全或文件分支显露 | 修对应 owner |
分支证明以后，每次只改一个变量。换模型就别同时换 key；换 key 就别同时改 payload；换输入文件就别同时换端点。持续配额压力可以再看 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 和输入文件。