Gemini API 错误处理实战指南：从 503 报错到自动重试的完整方案

Gemini API 错误处理实战指南：从 503 报错到自动重试的完整方案

【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook

凌晨两点，一次再普通不过的generate_content调用，返回的不是答案，而是一行503 Service Unavailable。Gemini API 错误处理不是可选项：网络抖动、临时过载、配额耗尽，任何一条都能把线上服务打成间歇性故障。这篇指南只解决一个问题——让失败的调用自己恢复。全部方案基于官方 cookbook 仓库的错误处理示例。

🔍 如何区分瞬态错误与 API 限流

重试之前先分类。拿错状态码乱重试，只会白白烧掉配额。

错误类型	典型状态码	成因	正确反应
瞬态错误	500 / 502 / 503 / 504	网络抖动、服务器临时过载	退避重试，通常成功
请求超时	408	网关或中间环节超时	调超时或单次重试
API 限流	429	超出配额（RPM/TPM）	先退避等待，再重试
鉴权 / 参数错误	400 / 401 / 403	Key 错误、请求体不合法	不要重试，先修代码

三个判断要点：

• 瞬态错误是最友好的一类：服务端只是暂时忙，退避重试基本都能成功
• 429 不算瞬态错误：限流意味着你撞上了配额，立刻重试等于反复敲一扇锁着的门，必须先退避
• 除 408/429 外的 4xx 都是你的 bug：重试改变不了 400 还是 400，修请求体比写重试循环更优先

内置重试 vs 手动 retry：先选路线再写代码

恢复机制有两条路，先对比再动手：

内置自动重试	手动 retry 库
启用方式	API 调用时传request_options	用retry装饰器包一层函数
额外代码量	几乎为零	需自己写predicate和退避参数
控制粒度	覆盖常见场景即可	精确：哪些异常重试、延迟多少、多久放弃，全在手里
适用场景	一般调用，想快速提升可靠性	需要按错误类型差异化处理的复杂流程

默认走内置：google-genai的重试逻辑与它抛出的异常体系是对齐的，重复造轮子只增加维护成本。只有需要细粒度控制时才走手动，比如想让 429 退避得比 503 更久。

把错误处理想成修一座城堡：限流是吊桥，放下就拦车；重试是塔楼，扛住几轮冲击。两者分工明确，才谈得上防御。

内置重试怎么开：最小落地方案

内置路线只需要在客户端上挂一份HttpRetryOptions，核心参数四个：

• initial_delay：首次重试前等待秒数
• maximum_delay：单次退避上限
• multiplier：延迟增长乘数，决定退避曲线的陡峭程度
• http_status_codes：触发重试的状态码，默认覆盖 408、429、500、502、503、504

手动路线的关键在predicate：用它圈定哪些异常值得重试。示例里直接判定exception.code in {408, 429, 500, 502, 503, 504}，一个白名单就把瞬态错误和限流都圈了进去；再配初始延迟、最大延迟和乘数，退避曲线就完整了。两条路线的参数逻辑是相通的，从内置切到手动没有学习成本。

⚠️ 验证与生产避坑：模拟 503、超时和日志

上线前先自证机制有效：

• 写个测试函数模拟 503：让首次调用故意抛503 Service Unavailable，第二次放行。如果重试没生效，这个测试会立刻红给你看——别等到生产事故才验证重试链路
• 超时参数是权衡不是调大：超时设太高，慢请求拖垮整条链路，错误暴露也变晚；设太低，正常波动又会被误杀。按你的业务响应时长定一个中间值，别拍脑袋给 60 秒
• 日志只记三个字段就够：错误码、时间戳、请求上下文。出问题时靠这三样复原现场，比截屏可靠得多

结语

优秀的错误处理不是让错误消失，而是让它可预期：瞬态错误交给重试，限流交给退避，剩下的才轮到你的代码。

【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook