企业官网建设流程全解析

Gemini API 错误码速查手册：从 503 到 429，逐个击破

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

调 Gemini API 调着调着突然蹦出个 503，或者点发送就甩你一脸 429？别慌，先别急着改代码，先查一下错误码，确认它是不是"能重试"的那一类。Gemini cookbook 项目的错误处理部分把这件事做得很实在：先分类，再决定走"自动重试"还是"手动退避"。

🔍 先分清哪些错能重试：Gemini API 错误码速查

日志里突然蹦出个 503，第一反应是重试？不，先看数字。常见错误码大致分两大类，处理方式完全不同：

可以重试的——瞬态错误：

• 408 Request Timeout：请求超时了，重试一下通常就好
• 429 Resource Exhausted：你手太快，服务器让你歇会儿（Gemini 429 限流是最常见的）
• 500 / 502 / 503 / 504：服务端忙、重启或网关抖了；503 = Service Unavailable，最典型的瞬态错误

不能重试的——你自己的问题：

• 400 Bad Request：请求本身有问题，重试一百次也没用
• 401 / 403：API key 没配好或没权限，重试只是重复翻车
• 404：模型名或端点不存在，先检查拼写

判断口诀：服务端状态不对就重试，你的请求不对就改代码。仓库里完整的错误处理示例在错误处理示例 Notebook。

⚡ 自动重试开启方法：改一处参数就搞定

分清错误之后，最省事的修法是让客户端库自己重试。创建genai.Client时把HttpRetryOptions通过http_options带进去就行，不用自己写任何重试逻辑：

retry_options = types.HttpRetryOptions(attempts=5, initial_delay=2.0, max_delay=30.0, http_status_codes=[408, 429, 500, 502, 503, 504]) client = genai.Client(api_key=GEMINI_API_KEY, http_options=types.HttpOptions(retry_options=retry_options))

四个旋钮：attempts（总共试几次）、initial_delay（首次重试等多久）、max_delay（最长等多久）、http_status_codes（哪些码触发重试）。有的 SDK 版本是调用时传request_options，这个仓库的示例则在建 client 时一次配好，思路都一样，这一步 90% 的情况就够了。

• 能覆盖：上面状态码列表里的瞬态错误，后台自动重试，用户基本无感
• 不能覆盖：400/401 这类 4xx 照样直接抛出来——这是好事，重试也没用
• 略不足：没法按错误类型定制处理，也看不到"我重试过了"的痕迹，观察性得靠日志补

🛠️ 手动重试策略配置：用 retry 库搭精细退避

想精确控制"怎么等、何时放弃"，或者给同一个函数包一层自动重试，就用retry库自己配。你只需要关心三件事：

1. 哪些错重试：写一个predicate，只放 code 在{408, 429, 500, 502, 503, 504}里的errors.APIError过
2. 怎么等：指数退避——initial=2.0从 2 秒起步，multiplier=2.0每次翻倍，maximum=64.0封顶 64 秒
3. 何时放弃：timeout=600是总预算，超了直接抛，不让它无限挂下去

@retry.Retry(predicate=if_genai_transient_error, initial=2.0, maximum=64.0, multiplier=2.0, timeout=600) def generate_with_retry(prompt): return client.interactions.create(model=MODEL_ID, input=prompt)

这样一包装，429 就从"打断用户的异常"变成了"等几秒再试"的内部事件。想要更手动的 API 重试策略细节，翻错误处理示例 Notebook即可。

🧪 503 错误自测流程：三步确认重试真的生效

"我觉得它生效了"是最不靠谱的事。故意触发一次 503，看它会不会乖乖重试：

1. 故意失败一次：在函数里第一次调用时故意抛errors.ServerError（503 Service Unavailable），后续调用走真实 API
2. 看输出：正确行为是先打印Error: 503 ...，然后重试并成功；如果一次成功却没有任何重试痕迹，说明predicate没接住这个异常
3. 反向验证：把异常换成 400，确认它不重试——只重试该重试的，才是对的

这个自测套路示例 notebook 里现成就有，照着把 cell 抄下来跑就行。

错误处理容易踩的坑：三处

超时不是越大越好。遇到ReadTimeout或DeadlineExceeded，把timeout（默认 600 秒）调大是合理的；但设得过高会拖慢错误检测、占着连接不放，该失败得快就让它快失败。

日志别省。每次重试都记下：错误码 + 时间戳 + 请求上下文（模型名、重试次数）。没有错误码，两周后你只能对着日志猜。

配额不够别硬刚。429 成片出现时，不是网络问题，是配额真用完了，重试越多被限得越狠。正确姿势是走官方配额申请流程提额；其他场景的入门示例可以看Gemini API 快速上手目录。

错误处理的目标不是消灭错误——503 和 429 总会有。而是让它们发生时用户无感：先分类、先自动重试、不够再手动退避，上线前自测一遍。做到这些，红色的报错也就不那么吓人了 🚀

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