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 / 403Key 错误、请求体不合法不要重试先修代码三个判断要点瞬态错误是最友好的一类服务端只是暂时忙退避重试基本都能成功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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考