# Nano Banana Pro 503 模型过载：Deadline expired 怎么处理？

> 503 UNAVAILABLE 和 Deadline expired 可以同时出现。先确认是谁返回了错误，再在原接口上有限重试；达到次数或等待预算就停止并排队，只有拿到满足原要求的可用图片才算恢复。

- URL: https://blog.laozhang.ai/zh/posts/fix-gemini-3-pro-image-503-overloaded
- Published: 2026-02-23
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 故障排查
- Tags: Gemini API, 503 错误, Deadline expired, Nano Banana Pro, 图片生成

---
**Nano Banana Pro 返回 HTTP 503 时，先确认错误来自哪一段服务，再做有限的退避重试。** 即使消息是 `Deadline expired before operation could complete.`，只要实际响应仍是 `503 UNAVAILABLE`，也不能仅凭这句话改判为 504。等待超过产品允许的时间、重试次数用完，或者错误变了，就停止这轮重试，转入排队或对应错误的排查。

最先做的三件事是：保留状态码和请求标识；暂停同一任务的重复提交；在确认允许重放后，保持模型、接口和输出要求不变重试。**恢复的终点是拿到并保存可用图片，HTTP 200 本身还不够。**

下面按 Google 官方文档和公开历史案例解释判断方法。示例仅检查了离线决策逻辑，没有执行真实生图请求，也没有测量恢复时间、成功率或账单。

## 为什么 503 也会写 `Deadline expired`？

Google 官方论坛曾记录过下面这组错误。它属于 2025 年 12 月至 2026 年 1 月的历史讨论，使用的是当时的 Pro 预览模型，并不表示今天所有 Pro 请求都有同样故障。[原始讨论](https://discuss.ai.google.dev/t/servererror-503-unavailable-error-code-503-message-deadline-expired-before-operation-could-complete-status-unavailable/110949)

```json
{
  "error": {
    "code": 503,
    "message": "Deadline expired before operation could complete.",
    "status": "UNAVAILABLE"
  }
}
```

这段消息说明操作没有在某个截止时间前完成，但没有交代超时发生在服务内部的哪一步。它不能证明 GPU 不够、内部队列满了，也不能证明你的客户端等待时间太短。对收到这份响应的程序而言，明确的分类仍然是 503。

![同样出现截止时间措辞时，分别核对 503、504 和无 HTTP 响应，并按新结果与预算停止或继续的示意。](https://blog.laozhang.ai/posts/zh/fix-gemini-3-pro-image-503-overloaded/img/wording-branch.webp)

同样，`The model is overloaded` 可以提示服务过载，但不能推出固定高峰时段或具体恢复时间。HTTP 标准把 503 定义为响应服务暂时无法处理请求，过载和维护都是可能情况；Google 的排查文档建议对临时错误采用退避、随机抖动和次数上限。[HTTP 503 定义](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.4)、[Google 排查指南](https://ai.google.dev/gemini-api/docs/troubleshooting)

当前官方 Pro 模型 ID 是 `gemini-3-pro-image`。`gemini-3-pro-image-preview` 已列入停用记录，不能再把历史案例中的预览 ID 当作官方当前接入配置。若服务商仍使用旧名称，先查它自己的映射说明；名称相似不证明 Google 预览端点仍可用。[Pro 模型说明](https://ai.google.dev/gemini-api/docs/models/gemini-3-pro-image)、[模型停用记录](https://ai.google.dev/gemini-api/docs/deprecations)

## 先确认谁返回了错误，以及你使用哪种格式

从失败请求中保存：时间、目标主机和接口、模型 ID、HTTP 状态、结构化错误类型、请求标识和耗时。共享日志前去掉密钥、完整提示词和私有图片内容。

如果浏览器只显示“生成失败”，往后端查原始响应；如果后端拿到的是 HTML 503 页面，先查自己的反向代理或服务商网关。只有来源明确，才能把这个状态归到相应服务。**自己的网关返回 503，不等于 Google 模型返回 503。** HTTP 状态和响应体互相矛盾时，保留二者，查网关转换和上游日志，不让消息字符串替你做决定。

| 你实际收到什么 | 如何识别 | 下一动作 |
| --- | --- | --- |
| 原生 `generateContent` 错误响应 | HTTP 503；JSON 的 `error.code` 是数字 `503`，`status` 是 `UNAVAILABLE` | 来源核实后进入本页的有限恢复流程 |
| Google Python SDK 异常 | 读取异常的整数 `code` 和响应信息 | 按真实状态分流，核对 SDK 是否已经重试过 |
| Interactions 错误响应 | HTTP 503；错误类型是字符串 `service_unavailable` | 进入 503 流程，不套用旧接口的数字字段解析器 |
| HTTP 504 | 旧格式可见 `DEADLINE_EXCEEDED`；Interactions 对应 `deadline_exceeded` | 查返回 504 的服务和上游等待预算 |
| 超时或断线，没有 HTTP 响应 | 只有客户端异常，没有可核实的服务端状态 | 记录“结果未知”，先查原任务是否完成 |

Interactions 的字符串错误类型来自它自己的[错误代码表](https://ai.google.dev/gemini-api/docs/api-errors)；Google Python SDK 的整数异常字段可见[异常实现](https://github.com/googleapis/python-genai/blob/main/google/genai/errors.py)。不要在整个异常文本、提示词或日志中搜索 `503`、`deadline` 后直接分类，数字和单词可能出现在与当前响应无关的位置。

已有 `generateContent` 项目仍受支持。排障时保留原接口及其请求、响应解析方式；为了重试临时错误，没有必要同时迁移到 Interactions。两套格式如何构造和保存图片，见 [Nano Banana Pro API 调用指南](https://blog.laozhang.ai/zh/posts/nano-banana-pro-api-guide)。

## 真实 503：怎样重试，什么时候停止？

先暂停同一任务的并发副本，再决定这次失败能否重放。图片生成通常通过 POST 提交，不能把相同提示词、请求标识或本地任务编号当作服务端自动去重的凭据。收到错误也不能一概认定“绝对没有生成图片”。如果这条服务的语义不保证安全重放，就明确接受可能重复生图和费用的代价，或者先查可用的任务结果，再发下一次请求。[HTTP 非幂等请求的重试条件](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2)

确认可以重试后，按以下顺序恢复：

1. **保持原请求要求。** 使用同一提供方、接口、模型、输入和输出规格。先观察原任务能否恢复，别同时换 SDK、密钥、模型和尺寸。
2. **读取 `Retry-After`。** 它可能是等待秒数，也可能是 HTTP 日期。等待值超过当前交互剩余预算时，把任务延后，不能把它压短后提前发送。[字段定义](https://www.rfc-editor.org/rfc/rfc9110.html#section-10.2.3)
3. **没有等待指示时，做指数退避并加入随机抖动。** 等待随失败次数增加，随机错开请求，避免所有工作进程同时重试。产品应设定总尝试次数、总耗时和单次请求预算，而不只设“睡几秒”。
4. **每次返回后重新分类。** 仍是 503 才继续这轮策略；变成 429、鉴权错误、参数错误或结果未知，就立即退出。拿到正常响应后检查图片，而不是继续重试。
5. **到达任一上限就停。** 能异步完成的任务进入队列；必须立即完成的交互返回清楚的暂不可用状态，让用户选择稍后再试或接受备用方案。

### 一个有明确边界的离线决策示例

下面是 Python 3 标准库函数，**只决定下一步，不发送请求、不保存图片，也不是完整 API 客户端**。调用方需要先核实错误来源和状态，提供已用次数、已耗时间及允许重放的判断。

示例选用最多 3 次总尝试、45 秒交互预算，并为下一次请求预留 12 秒。无 `Retry-After` 时，前两次失败后的随机等待窗口分别是 0～2 秒和 0～4 秒。这些数字是展示控制方法的产品配置，不能当作 Google 的固定超时、恢复时长或并发限额。

```python
from datetime import timezone
from email.utils import parsedate_to_datetime


def next_step(http_status, attempts_used, elapsed_seconds, *,
              issuer_verified, may_replay, now_utc,
              retry_after=None, jitter_fraction=0.5):
    max_attempts = 3                 # 包含首次请求
    total_budget = 45.0
    next_request_budget = 12.0

    if not issuer_verified:
        return "查响应来源", None
    if http_status is None:
        return "查原任务结果，禁止自动重放", None
    if http_status == 200:
        return "检查并保存图片", None
    if http_status != 503:
        return "退出503流程，按新错误排查", None
    if not may_replay:
        return "查原任务结果或确认重放代价", None
    if attempts_used >= max_attempts:
        return "停止本轮，转入队列或返回失败", None
    if not 0.0 <= jitter_fraction <= 1.0:
        raise ValueError("随机比例必须在0到1之间")

    if retry_after is None:
        window = min(8.0, 2.0 ** attempts_used)
        delay = window * jitter_fraction
    else:
        value = retry_after.strip()
        if value.isascii() and value.isdecimal():
            delay = float(int(value))
        else:
            try:
                target = parsedate_to_datetime(value)
                if target.tzinfo is None or now_utc.tzinfo is None:
                    raise ValueError("日期必须包含时区")
                delay = max(0.0, (target.astimezone(timezone.utc)
                                 - now_utc.astimezone(timezone.utc))
                            .total_seconds())
            except (TypeError, ValueError, OverflowError):
                return "检查无效的Retry-After", None

    if elapsed_seconds + delay + next_request_budget >= total_budget:
        return "延后执行，保留服务要求的等待时间", delay
    return "等待后在原接口重试", delay
```

实际调度器收到“等待后在原接口重试”才等待并发送下一次请求；每次都更新耗时和次数。生产环境用单调时钟计算耗时，HTTP 日期比较使用有时区的当前时间。`jitter_fraction` 应传入 0～1 的随机值，这里默认的 0.5 便于离线复算。

例如，首次 503 已耗 8 秒、没有 `Retry-After`，按示例得到等待 1 秒，再预留 12 秒，总计 21 秒，可以继续。第二次失败累计耗时 22 秒，等待 2 秒后总计 36 秒，也可继续。第三次仍然 503，次数上限先让它停止。若首次响应要求等 40 秒，`8 + 40 + 12 = 60` 秒已超过预算，任务应延后，不能为了挤进 45 秒而只等 2 秒。

这些分支用合成时间与响应做过离线检查。12 秒是否足以完成你的生图任务需要另行测量；真实调度器还必须控制单次请求的截止时间，不能因为这个函数检查了预算，就声称整个网络调用会在 45 秒内结束。

### 只让一层负责重试，避免请求成倍增加

应用、SDK 和网关不能各自默默重试。若应用最多尝试 3 次，而底层每次最多发 5 次，上游可能收到 15 次调用；失败后的等待也会叠加。选择一层统一负责，其他层明确配置或计入预算。

Google 排查文档写到 Python SDK 会自动重试 4 次；但截至 2026 年 10 月 6 日读取的公开主分支实现中，`retry_options=None` 对应一次尝试，显式提供默认选项时总尝试数为 5。该源码快照只说明所读实现，不代表你的安装版本或所有接口行为。应检查实际版本和配置，不能只凭“SDK 默认会重试”再套一个循环。[排查文档](https://ai.google.dev/gemini-api/docs/troubleshooting)、[客户端实现](https://github.com/googleapis/python-genai/blob/main/google/genai/_api_client.py)、[配置类型](https://github.com/googleapis/python-genai/blob/main/google/genai/types.py)

## 504 和客户端无响应，处理方法有什么区别？

**收到 504，先查哪个网关或服务等待上游超时；没有收到响应，先查原任务结果。** 它们都可能表现为用户等不到图片，但程序掌握的信息不同。

HTTP 504 表示网关或代理没有及时收到上游回复。Google Interactions 的 `deadline_exceeded` 也对应 504。既然服务已经返回超时错误，只把本地等待时间从 60 秒改到 180 秒，不会让那次已结束的服务端操作继续完成。[HTTP 504 定义](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.5)、[Interactions 错误代码](https://ai.google.dev/gemini-api/docs/api-errors)

这时核对客户端、自己的网关和供应商接口的等待上限，找出最先终止的一层。如果是你控制的网关先截断、任务允许更久等待，可以调整那一层；如果是供应商服务端先返回 504，就应考虑延后、减小允许调整的请求负载，或转为该接口实际支持的异步流程。一次只调整一个变量，并重新观察结果。

客户端超时或断线时，服务可能仍在生成，甚至已经完成。先查已有任务 ID、保存的响应或供应商实际提供的结果查询功能，再决定是否重放。没有查询能力时，保留“结果未知”，不要伪造一个 503 或 504 状态。Google Interactions 的已保存对象和服务商自己的任务查询不是同一种能力，不能给任意网关臆造一个通用查询地址。

降低 4K 到 2K 可以作为接受较低输出规格后的新尝试，但不能称为“原 4K 请求已经恢复”。也不要给 Pro 加上其他模型教程里的“关闭 thinking”参数：Pro 的 thinking 不能关闭。[Pro 图片生成说明](https://ai.google.dev/gemini-api/docs/image-generation?hl=en)

## 怎样确认原任务恢复，而不是只看到 200？

![保持原请求条件、观察错误变化并选择下一步的示意图](https://blog.laozhang.ai/posts/zh/fix-gemini-3-pro-image-503-overloaded/img/verify-route-out.webp)

在原提供方和原接口上重试，满足以下条件才把任务标为完成：

- 响应没有错误，任务已经完成；排队中、处理中都不算完成。
- 按当前接口的响应格式找到真正的模型图片输出。`generateContent` 从 `candidates` 的内容中读取 `inlineData`；Interactions 从 `steps` 的 `model_output.content` 读取图片的 `data` 和 `mime_type`，二者不能混用。
- 图片数据能解码，MIME 与实际文件相符，保存后的文件能打开；文字回答或空响应不算图片结果。
- 输出达到原任务要求的尺寸、比例和用途。原任务要求 4K，却只拿到另一模型的 1K 图片，属于备用产出，不是同一条件下恢复。

保存图片和完整响应的实现见 [Pro API 响应解析与图片落盘](https://blog.laozhang.ai/zh/posts/nano-banana-pro-api-guide)。如果 HTTP 200 却没有图片，查看当前接口返回的拒绝、安全、无图或其他结束原因，再检查请求和解析器；不要把它继续当作 503 重试，也不要通过降低安全要求处理被拦截的内容。[Google 图片输出说明](https://ai.google.dev/gemini-api/docs/image-generation?hl=en)、[API 错误说明](https://ai.google.dev/gemini-api/docs/api-errors)

如果错误改变，下一步也随之改变：

| 新结果 | 该查什么 |
| --- | --- |
| 429 | 读限额详情，分清分钟速率、每日配额和花费窗口；按 [Gemini 图片 429 排查](https://blog.laozhang.ai/zh/posts/gemini-image-429-rate-limit) 进入对应分支，避免继续套用本页的 503 重试预算 |
| 400 | 查参数、请求结构和前置条件，用同接口的有效格式修正后再发 |
| 401 / 403 | 核对鉴权和权限归属；更换提示词、延长等待不会修复权限问题 |
| 402 | 查当前提供方的余额或结算条件，再决定是否继续调用 |
| 404 | 查接口路径和当前模型 ID，尤其是仍使用旧预览名的配置 |
| 其他 5xx | 保留具体状态和请求标识，按该服务文档决定；不要把所有 5xx 都视为同样可重试 |

## 一直 503 时，排队还是换模型？

**原规格必须保留时，优先延后或排队；交付时间必须保留、规格可以让步时，才启用明确的备用方案。** 持续 503 时暂停这一条失败接口的新提交，用有限数量的探测请求判断是否恢复，避免队列中的每个任务都独立发起重试。恢复后逐步放行，并保留已完成图片，不从头重跑整批任务。

队列应记录本地任务编号、原提供方和接口、模型、输入引用、输出要求、已尝试次数、下一执行时间及结果状态。本地编号用于应用内防止重复调度，并不自动获得 Google 的幂等保证。服务要求等待较久时，下一执行时间不能早于该等待要求；任务超过业务有效期或用户取消时应停止，而不是在后台无限重放。

备用方案的代价要提前讲清：

| 选择 | 可以满足什么 | 需要接受的变化 |
| --- | --- | --- |
| 延后原 Pro 请求 | 保留原模型和输出要求 | 交付时间延迟，仍需监测恢复和队列有效期 |
| Pro 4K 改为 2K | 先取得较低规格图片 | 细节和像素要求改变，不能保证重试成功；放大后的图也不等于原生 4K |
| 换当前可用的其他图像模型 | 在另一模型上尝试交付 | 文字、构图、编辑和参考图保持效果需按任务确认，不保证等价 |
| 换服务商接口 | 使用另一套服务和计费条件 | 鉴权、请求结构、解析、规格与数据条件可能改变，不能证明原接口恢复 |

截至 2026 年 10 月 7 日，Google 已有独立模型 `gemini-nano-banana-2.1`；它不是 Pro 的另一个名字。旧 `gemini-2.5-flash-image` 已列入停用记录，`gemini-3.1-flash-image` 也有后续停用安排，因此不要直接复制旧文章里的预览模型备用代码。[当前图片模型文档](https://ai.google.dev/gemini-api/docs/image-generation?hl=en)、[停用安排](https://ai.google.dev/gemini-api/docs/deprecations)

规格和费用也要成套比较。Google 标准 Pro 图片输出价格中，1K / 2K 约为每张 0.134 美元，4K 为每张 0.24 美元，输入、文字、思考等费用另计；这些是对应模式的输出计费，不能当作整次请求的封顶价。[官方价格](https://ai.google.dev/gemini-api/docs/pricing)

例如，LaoZhang 的公开 Pro 文档标示每次 0.09 美元，并说明 HTTP 200 即计费，即使没有图片；这是该提供方的口径，最新控制台价格仍需在使用前确认。其原生兼容 `generateContent` 与 OpenAI 兼容接口也不能互换字段；后者文档标示固定 1:1、1K、非流式，不能直接替代要求 4K 的 Google 请求。本站由 LaoZhang 团队运营，这些公开条件不构成更低故障率或恢复时长保证。[LaoZhang Pro 接口文档](https://docs.laozhang.ai/api-capabilities/nano-banana-pro-image)

## 常见问题

### 503 会持续多久？

没有统一时长。503 本身不提供恢复倒计时；有 `Retry-After` 时按它安排最早重试时间，没有时按产品的有限退避策略处理。公开历史案例中的“后来恢复了”不能变成所有账户的恢复承诺。[HTTP 503 与等待字段](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.4)

### 已经付费了，还会模型过载吗？

会，付费不保证没有 503。Google 论坛有已付费 Tier 1 用户报告 Pro 返回 503 的历史案例。该案例能说明付费与此类错误可以同时出现，不能推出当前账户的故障率；也没有依据把升级账单层级或购买优先通道当作这次 503 的保证修复。[付费用户的历史报告](https://discuss.ai.google.dev/t/503-error-while-generate-content-model-gemini-3-pro-image-preview-tire1-paid/112180)

### 重试会不会重复出图或重复扣费？

可能，尤其是客户端没有收到响应时，原请求结果仍未知。先查原任务或已有产物，只重放未完成且已允许重放的任务；收费按实际提供方和错误类型核对。不能从“看到 503”推导所有失败免费，也不能把网关 200 无图视为免费。相同提示词和本地任务 ID 不自动保证服务端去重。[HTTP 重试条件](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2)、[LaoZhang 的计费说明](https://docs.laozhang.ai/api-capabilities/nano-banana-pro-image)

### 换一个 API Key 能解决 503 吗？

通常不应先换密钥。503 是响应服务暂不可用的分支，鉴权和配额要根据实际错误另查。Google 配额按项目计算，同项目多建密钥也不会得到独立配额。只有状态已变为 401 / 403，或确认运行配置使用了错误项目，才处理相应鉴权问题。[Google 速率限制范围](https://ai.google.dev/gemini-api/docs/rate-limits)

## 参考来源

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

- [原始讨论](https://discuss.ai.google.dev/t/servererror-503-unavailable-error-code-503-message-deadline-expired-before-operation-could-complete-status-unavailable/110949) (discuss.ai.google.dev)
- [HTTP 503 定义](https://www.rfc-editor.org/rfc/rfc9110.html) (rfc-editor.org)
- [Google 排查指南](https://ai.google.dev/gemini-api/docs/troubleshooting) (ai.google.dev)
- [Pro 模型说明](https://ai.google.dev/gemini-api/docs/models/gemini-3-pro-image) (ai.google.dev)
- [模型停用记录](https://ai.google.dev/gemini-api/docs/deprecations) (ai.google.dev)
- [错误代码表](https://ai.google.dev/gemini-api/docs/api-errors) (ai.google.dev)
- [异常实现](https://github.com/googleapis/python-genai/blob/main/google/genai/errors.py) (github.com)
- [客户端实现](https://github.com/googleapis/python-genai/blob/main/google/genai/_api_client.py) (github.com)
- [配置类型](https://github.com/googleapis/python-genai/blob/main/google/genai/types.py) (github.com)
- [Pro 图片生成说明](https://ai.google.dev/gemini-api/docs/image-generation?hl=en) (ai.google.dev)
- [官方价格](https://ai.google.dev/gemini-api/docs/pricing) (ai.google.dev)
- [付费用户的历史报告](https://discuss.ai.google.dev/t/503-error-while-generate-content-model-gemini-3-pro-image-preview-tire1-paid/112180) (discuss.ai.google.dev)
- [Google 速率限制范围](https://ai.google.dev/gemini-api/docs/rate-limits) (ai.google.dev)