Gemini API 错误码完整速查表：三层防御搞定 429 与 503

Gemini API 错误码完整速查表三层防御搞定 429 与 503【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook线上服务深夜突然弹出 503 Service Unavailable监控面板一片红。如果你也被 Gemini API 错误码缠上这篇文章能在 3 分钟内给你一套可直接落地的流程先看错误码速查表再搭三层错误处理防线最后掌握四步排障法。错误码速查这 6 个数字到底什么意思官方示例里反复出现的错误码集中在下表。报错时先对照定位再谈动作错误码常见含义典型原因处理动作408请求超时服务器没及时收到完整请求多为网络波动回退重试429频率限制rate limit调用量过高超出模型的默认配额先降频间隔后重试或申请更高配额500服务器内部错误服务端异常多为瞬态重试502网关错误上游服务异常回退重试503服务暂不可用服务器过载或维护中重试切忌连续轰炸接口504网关超时上游响应过慢重试并顺带检查超时设置速查表整理自官方示例 quickstarts/Error_handling.ipynb。如果只记一条表里 429 和 5xx 大多属于瞬态错误正确的动作是等一等再试429 是例外——它虽是 4xx但解法不是更快重试而是慢下来。三层错误防御体系 ️调用前、中、后各挡一道把错误挡在门外像给硬件布线上电前先查电表运行中盯电流还得留保险丝。下面这张项目 IoT 示例里的接线图分层的感觉就很到位。调用前先核对配额再定超时发请求之前先确认模型的配额还够用。429 出现一次是信号连续出现就是事故预演该降并发就先降并发。再来看超时SDK 默认超时高达 600 秒如果你真碰到ReadTimeout或DeadlineExceeded可以调大timeout参数放宽等待。但别盲目拉到极高否则一次失败的调用要让你干等很久错误检测反而被拖慢了。调用中最小配置启用 SDK 内置重试客户端库自带重试能力调用时传入重试选项即可大部分瞬态错误不用你动手就能扛下来。示例 quickstarts/Error_handling.ipynb 里只用了四行types.HttpRetryOptions( attempts5, initial_delay2.0, max_delay30.0, http_status_codes[408, 429, 500, 502, 503, 504], )含义很直白最多尝试 5 次首次重试前等 2 秒延迟上限 30 秒且只有速查表里那 6 个码才触发重试。简单场景这就够了。调用后回退重试自写日志必留需要更精细的控制时用retry库自己搭回退机制。核心是predicate参数——它像个门卫只有 408、429、503 这类瞬态异常能放行其余一律拦下直接抛出。同时把错误码、时间戳和请求上下文写进日志出事才能回溯。示例里还藏了一个验证技巧故意让第一次调用抛 503看重试机制是否真的接手。报错时的四步排障流程错误还是躲不掉按顺序走这四步别跳步看错误码对照速查表判断是瞬态值得重试还是真故障。查频率限制见到 429先查模型配额和自己的调用频率这是最常见的原因。查网络408、504 和各类超时多与网络波动或服务端过载有关换网段或稍等片刻再试一次。核对请求参数重试仍救不回来问题多半在请求侧——API Key、模型名、字段格式逐项过一遍。速查表管识别三层防御管拦截四步流程管排障。能交给内置重试的就别自己造轮子。实战里我学到的是别跟 503 较劲把代码写成会“退一步再进”的人报错自然少了一半。【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考