Gemini API 错误处理实战429、503、超时怎么查、怎么修、怎么验证【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook第一次在生产环境调用 Gemini API回包不是答案而是一行503 Service Unavailable隔几秒再试又变成429 Too Many Requests碰上长任务还会撞见ReadTimeout。Gemini API 错误处理的关键不是见错就重试而是先分清错误性质再决定重试加在哪一层。本文基于仓库里的 quickstarts/Error_handling.ipynb按识别 → 处置 → 验证的排查动线走完整个流程。先给错误定性值不值得重试错误的责任方不同处置方式完全相反。如果把一次 API 调用看成像硬件电路一样的信号链——请求出发、网络传输、服务端处理、响应回传任何一段断了都会报错但断点不同修法不同。上图来自仓库的 examples/iot/esp32/voice_led_controller/ 示例麦克风的声音要经过音频板、主控板才能点亮 LEDAPI 调用的每一步也都有对应断点。具体到 Gemini API先按状态码分三类可重试的瞬态错误408、429、500、502、503、504。前者是限流后者是网络或服务器临时故障等一等再发大概率成功客户端错误其余 4xx如 400请求本身就有问题重试一万次结果都一样该改参数而不是加延时超时错误ReadTimeout、DeadlineExceeded说明请求太慢而不是失败。SDK 默认超时是 600 秒它属于调整等待策略的问题不是重发的问题。判断口诀看到那六个瞬态码才考虑重试看到普通 4xx 先查请求看到超时先评估任务是不是真的很大。省事方案让 SDK 自动重试 Gemini API 错误确认是瞬态错误后最省事的用法是google-genai内置的重试机制创建 client 时传入一份HttpRetryOptions整个应用就获得自动重试能力。它只有四个参数含义很直白attempts总共尝试几次含首次调用initial_delay/max_delay重试间隔从多长开始、最长拉到多少http_status_codes哪些状态码触发重试正好填上面那组瞬态码。cookbook 里的参考配置是试 5 次、首次延迟 2 秒、最大延迟 30 秒。这套方案的重试逻辑和 SDK 实际抛出的异常天然对齐你不需要关心底层细节代价是粒度粗——所有错误共用一套策略也无法在某次重试后插入自定义逻辑比如降级到备用模型。需要精细控制时手写指数退避当你的要求变成只对 Gemini 的异常重试、间隔按 2、4、8……64 秒递增、总窗口 10 分钟时就用google.api_core的retry装饰器自己包一层。核心是predicate参数写一个函数判断异常是不是google.genai.errors.APIError且code落在{408, 429, 500, 502, 503, 504}里是才重试否则直接抛出。参数上initial2.0、multiplier2.0、maximum64.0组合出的间隔序列是 2s、4s、8s……封顶 64stimeout600则是整个重试过程的总闸门防止无限等待吃光资源。指数退避比固定间隔好在服务恢复往往不是瞬间的渐进逼近比齐刷刷重放温和得多。用一个假的 503 验证整条链路重试代码写完别等生产故障才验证。cookbook 给了个巧法写一个包装函数用调用计数让第一次故意抛errors.ServerError(503, ...)第二次走真实调用。如果机制生效你会先看到一行Error: 503 Service Unavailable随后函数照常返回模型结果——识别 → 退避 → 重试 → 成功整条链路就此闭环。超时也顺手处理掉长任务频繁撞ReadTimeout时在http_options里把timeout调大cookbook 示例是 15 分钟。但别无脑调高超时设得越大真正出错的请求要干等的时间也越长错误发现反而被拖慢。上线前自检清单六个瞬态状态码是否都进了重试白名单普通 4xx 是否被明确排除重试总时长是否有上限最坏情况下用户要等多久日志能否还原第几次重试、间隔多少、最终成功还是放弃。建议先把 quickstarts/Error_handling.ipynb 从头跑一遍再对照 quickstarts/Get_started.ipynb 补全调用参数重试策略就有了落地的土壤。【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gemini API 错误处理实战：429、503、超时怎么查、怎么修、怎么验证
Gemini API 错误处理实战429、503、超时怎么查、怎么修、怎么验证【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook第一次在生产环境调用 Gemini API回包不是答案而是一行503 Service Unavailable隔几秒再试又变成429 Too Many Requests碰上长任务还会撞见ReadTimeout。Gemini API 错误处理的关键不是见错就重试而是先分清错误性质再决定重试加在哪一层。本文基于仓库里的 quickstarts/Error_handling.ipynb按识别 → 处置 → 验证的排查动线走完整个流程。先给错误定性值不值得重试错误的责任方不同处置方式完全相反。如果把一次 API 调用看成像硬件电路一样的信号链——请求出发、网络传输、服务端处理、响应回传任何一段断了都会报错但断点不同修法不同。上图来自仓库的 examples/iot/esp32/voice_led_controller/ 示例麦克风的声音要经过音频板、主控板才能点亮 LEDAPI 调用的每一步也都有对应断点。具体到 Gemini API先按状态码分三类可重试的瞬态错误408、429、500、502、503、504。前者是限流后者是网络或服务器临时故障等一等再发大概率成功客户端错误其余 4xx如 400请求本身就有问题重试一万次结果都一样该改参数而不是加延时超时错误ReadTimeout、DeadlineExceeded说明请求太慢而不是失败。SDK 默认超时是 600 秒它属于调整等待策略的问题不是重发的问题。判断口诀看到那六个瞬态码才考虑重试看到普通 4xx 先查请求看到超时先评估任务是不是真的很大。省事方案让 SDK 自动重试 Gemini API 错误确认是瞬态错误后最省事的用法是google-genai内置的重试机制创建 client 时传入一份HttpRetryOptions整个应用就获得自动重试能力。它只有四个参数含义很直白attempts总共尝试几次含首次调用initial_delay/max_delay重试间隔从多长开始、最长拉到多少http_status_codes哪些状态码触发重试正好填上面那组瞬态码。cookbook 里的参考配置是试 5 次、首次延迟 2 秒、最大延迟 30 秒。这套方案的重试逻辑和 SDK 实际抛出的异常天然对齐你不需要关心底层细节代价是粒度粗——所有错误共用一套策略也无法在某次重试后插入自定义逻辑比如降级到备用模型。需要精细控制时手写指数退避当你的要求变成只对 Gemini 的异常重试、间隔按 2、4、8……64 秒递增、总窗口 10 分钟时就用google.api_core的retry装饰器自己包一层。核心是predicate参数写一个函数判断异常是不是google.genai.errors.APIError且code落在{408, 429, 500, 502, 503, 504}里是才重试否则直接抛出。参数上initial2.0、multiplier2.0、maximum64.0组合出的间隔序列是 2s、4s、8s……封顶 64stimeout600则是整个重试过程的总闸门防止无限等待吃光资源。指数退避比固定间隔好在服务恢复往往不是瞬间的渐进逼近比齐刷刷重放温和得多。用一个假的 503 验证整条链路重试代码写完别等生产故障才验证。cookbook 给了个巧法写一个包装函数用调用计数让第一次故意抛errors.ServerError(503, ...)第二次走真实调用。如果机制生效你会先看到一行Error: 503 Service Unavailable随后函数照常返回模型结果——识别 → 退避 → 重试 → 成功整条链路就此闭环。超时也顺手处理掉长任务频繁撞ReadTimeout时在http_options里把timeout调大cookbook 示例是 15 分钟。但别无脑调高超时设得越大真正出错的请求要干等的时间也越长错误发现反而被拖慢。上线前自检清单六个瞬态状态码是否都进了重试白名单普通 4xx 是否被明确排除重试总时长是否有上限最坏情况下用户要等多久日志能否还原第几次重试、间隔多少、最终成功还是放弃。建议先把 quickstarts/Error_handling.ipynb 从头跑一遍再对照 quickstarts/Get_started.ipynb 补全调用参数重试策略就有了落地的土壤。【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考