Gemini API 3类报错应对全指南自动重试、超时与指数回退配置详解【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook半夜被监控叫醒日志里全是503 Service Unavailable或者一个长文本任务卡了十分钟最后抛出一条ReadTimeout。用 Gemini API 写生产代码这三类问题你迟早会撞上瞬态错误、限流、超时。好消息是Gemini API Cookbook 仓库里的 quickstarts/Error_handling.ipynb 把应对方案整理成了两种路线——SDK 自带重试和手动指数回退——本文按先判断、再分层的顺序把它拆开讲。先对号入座你遇到的是哪种错误处理之前先判断类型三类错误的特征和解法完全不同现象报错特征典型原因处置动作500/502/503/504、408瞬态错误网络抖动、服务端过载过一会儿就好交给自动重试覆盖这 6 个状态码429超过该模型的默认频率限制RPM/TPM查官方模型文档的配额表不够就申请提额同时加回退ReadTimeout/DeadlineExceeded单次调用超过默认超时600 秒在http_options里手动调大timeout注意区分429 重试能救但治标不治本。每个 Gemini 模型的默认限流值列在官方模型文档里配额确实不够用时正确动作是申请提高速率限制而不是无限刷。第一层一行 http_options 打开 SDK 内置重试用google-genai2.9.0 及以上版本时最省事的方案是google.genai.types里的HttpRetryOptions。它的重试行为与 SDK 实际抛出的异常体系保持一致不用你自己写异常匹配逻辑。from google import genai from google.genai import types retry_options types.HttpRetryOptions( attempts5, initial_delay2.0, max_delay30.0, http_status_codes[408, 429, 500, 502, 503, 504], ) custom_client genai.Client( api_keyGEMINI_API_KEY, http_optionstypes.HttpOptions(retry_optionsretry_options), ) custom_client.interactions.create( modelMODEL_ID, inputprompt, ).steps[-1].content[0].text四个参数各管一件事参数含义取值建议attempts放弃前的总尝试次数5 次能覆盖大多数抖动initial_delay首次重试前等待秒数2.0 秒起步max_delay两次重试之间的延迟上限秒30 秒封顶避免拖垮线程http_status_codes哪些状态码触发重试把 6 个瞬态码全列进去改完客户端构造方式后业务代码一行不动瞬态错误大部分被静默消化掉。第二层手动精细控制当开箱即用不够用——比如超时场景、或者你想对不同错误区别对待——就手动接管。ReadTimeout / DeadlineExceeded 时怎么调超时默认超时是 600 秒。长文本生成、长视频分析这类慢任务会撞线在http_options里指定timeout即可单位是毫秒custom_client genai.Client( api_keyGEMINI_API_KEY, http_optionstypes.HttpOptions(timeout15 * 60 * 1000), # 15 分钟 )一个提醒超时不是越大越好。设得太高真正的故障也会挂在那里干等错误发现被推迟、资源被白白占用。按你任务的 P99 耗时留余量而不是拍脑袋给 1 小时。用 retry 库写指数回退想要精确控制重试节奏用google.api_core的retry同类库还有backoff、tenacity核心是把哪些异常值得重试抽成一个predicate函数from google.api_core import retry from google.genai import errors def if_genai_transient_error(exception): return isinstance(exception, errors.APIError) and exception.code in {408, 429, 500, 502, 503, 504} retry.Retry( predicateif_genai_transient_error, initial2.0, # 首次等待 2 秒 maximum64.0, # 单次等待最多 64 秒 multiplier2.0, # 每轮翻倍 timeout600, # 600 秒内重试预算耗尽则放弃 ) def generate_with_retry(prompt): return client.interactions.create( modelMODEL_ID, inputprompt, )predicate决定了边界只有APIError且状态码在瞬态集合里才重试400这类参数错误会直接抛给你不会被无效重试拖住。等待序列是 2 → 4 → 8 … 封顶 64 秒timeout600保证总预算可控。自检故意失败一次验证重试真的生效代码写完不等于逻辑正确。照抄 notebook 里的验证手法包一个函数第一次调用时主动抛出errors.ServerError503后续调用走真实 API——from google.genai import errors retry.Retry( predicateif_genai_transient_error, initial2.0, maximum64.0, multiplier2.0, timeout600, ) def generate_content_first_fail(prompt): if not hasattr(generate_content_first_fail, call_counter): generate_content_first_fail.call_counter 0 generate_content_first_fail.call_counter 1 try: if generate_content_first_fail.call_counter 1: raise errors.ServerError( 503, {error: {code: 503, message: Service Unavailable, status: UNAVAILABLE}}, None, ) interaction client.interactions.create(modelMODEL_ID, inputprompt) return interaction.steps[-1].content[0].text except errors.ServerError as e: print(fError: {e}) raise预期输出分两段先打印Error: 503 Service Unavailable随后第二次调用成功返回文案。看到这两段都出现才说明装饰器接住了异常、并且重试路径走通。503是故意模拟的服务端故障google-genai对这类瞬态失败抛的就是ServerError这一族拿它做测试靶子最贴近线上行为。行动清单给每个genai.Client挂上HttpRetryOptions状态码列表覆盖408, 429, 500, 502, 503, 504六个值。慢任务单独建客户端timeout按任务 P99 耗时上浮设置别全局拉高。在测试环境跑一遍首次必抛 503的自检验证确认日志里能同时看到报错和重试成功。【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考