企业官网建设流程全解析

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 个数字到底什么意思

官方示例里反复出现的错误码集中在下表。报错时先对照定位，再谈动作：

速查表整理自官方示例 quickstarts/Error_handling.ipynb。如果只记一条：表里 429 和 5xx 大多属于瞬态错误，正确的动作是等一等再试；429 是例外——它虽是 4xx，但解法不是更快重试，而是慢下来。

三层错误防御体系 🛡️：调用前、中、后各挡一道

把错误挡在门外，像给硬件布线：上电前先查电表，运行中盯电流，还得留保险丝。下面这张项目 IoT 示例里的接线图，分层的感觉就很到位。

调用前：先核对配额，再定超时

发请求之前，先确认模型的配额还够用。429 出现一次是信号，连续出现就是事故预演，该降并发就先降并发。再来看超时：SDK 默认超时高达 600 秒，如果你真碰到ReadTimeout或DeadlineExceeded，可以调大timeout参数放宽等待。但别盲目拉到极高，否则一次失败的调用要让你干等很久，错误检测反而被拖慢了。

调用中：最小配置启用 SDK 内置重试

客户端库自带重试能力，调用时传入重试选项即可，大部分瞬态错误不用你动手就能扛下来。示例 quickstarts/Error_handling.ipynb 里只用了四行：

types.HttpRetryOptions( attempts=5, initial_delay=2.0, max_delay=30.0, http_status_codes=[408, 429, 500, 502, 503, 504], )

含义很直白：最多尝试 5 次，首次重试前等 2 秒，延迟上限 30 秒，且只有速查表里那 6 个码才触发重试。简单场景，这就够了。

调用后：回退重试自写，日志必留

需要更精细的控制时，用retry库自己搭回退机制。核心是predicate参数——它像个门卫，只有 408、429、503 这类瞬态异常能放行，其余一律拦下直接抛出。同时把错误码、时间戳和请求上下文写进日志，出事才能回溯。示例里还藏了一个验证技巧：故意让第一次调用抛 503，看重试机制是否真的接手。

报错时的四步排障流程

错误还是躲不掉？按顺序走这四步，别跳步：

1. 看错误码：对照速查表判断是瞬态（值得重试）还是真故障。
2. 查频率限制：见到 429，先查模型配额和自己的调用频率，这是最常见的原因。
3. 查网络：408、504 和各类超时多与网络波动或服务端过载有关，换网段或稍等片刻再试一次。
4. 核对请求参数：重试仍救不回来，问题多半在请求侧——API Key、模型名、字段格式，逐项过一遍。

速查表管识别，三层防御管拦截，四步流程管排障。能交给内置重试的就别自己造轮子。实战里我学到的是：别跟 503 较劲，把代码写成会“退一步再进”的人，报错自然少了一半。

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