Gemini API 报错 400、403、429、500、503、504 怎么办：官方错误码对照，502 和 error 13 官方没列出时怎么查

本文根据 Gemini API 官方文档的「API errors」页和「Troubleshooting」页整理，资料核对于 2026-10-30。官方两页都没有出现 502，也没有出现「error 13」，这两种在下面单列一节说明。配图为本站整理的示意图，不是网页截图。

适用于谁

• 调用 Gemini API，返回 HTTP 400、403、429、500、503、504 的开发者；
• 在 Cursor、Cline、Cherry Studio 等工具里填了 Gemini API Key，看到报错的人；
• 搜「Gemini 报错 502」「Gemini error 13」的人。

结论先说

1. 官方错误页把错误分成三类：请求本身的问题（400、401、402、403、404、416 等，改请求或查账号，重试没用）、限流类（429，等一等再试）、服务端类（500、503、504）。
2. 429 有三种代码：rate_limit_exceeded（每分钟或每秒的请求或 token 超限）、quota_exceeded（日配额用完）、too_many_requests（短时间请求太多）。前者和后者等待后按指数退避重试，日配额则要等重置或申请提高。429 的详细讲解见 /guides/gemini-api-429-resource-exhausted。
3. 500 api_error：服务端意外错误，重试，持续就联系支持。503 service_unavailable：服务暂时过载或不可用，等待后按指数退避重试。504 deadline_exceeded：请求没在时限内完成，官方建议去掉或调大客户端的超时设置，让服务端用默认值。
4. 官方推荐的重试方式：指数退避，加随机抖动，设置最大重试次数；官方说明 Python SDK 默认对暂时性错误最多重试四次。
5. 502 和 error 13 官方页面里没有。先看官方状态页，确认不是官方故障，再按通用做法处理，见第三节。

图：本站根据 Gemini API 错误页 整理的示意图

一、请求类错误：重试没有用

排查页对 403 的几种情形写得更细：

• 项目被拒绝访问，或项目状态是 Restricted、Free tier unavailable、Payment needed、Unavailable；
• 免费层不可用：关联一个有效的 Cloud Billing 账号；
• 需要付款：处理欠费，或在账单页更新付款方式；
• Key 泄露或被封：官方会提示「API key was reported as leaked」，要在 AI Studio 里新建一个 Key。

Key 的创建和保管，可参考 /guides/gemini-api-python-quickstart。免费层和付费层的额度区别，见 /guides/gemini-api-free-tier-rate-limits 和 /guides/gemini-api-price-official。

二、限流和服务端错误：可以重试

另外官方页面还列了内容被拦截的代码（如 safety、prohibited_content、image_safety 等），官方说法是修改输入后再试；以及生成错误（如 malformed_function_call、no_image）。这些和网络、额度无关，是请求内容或模型输出方面的问题。

三、502 和 error 13：官方没写，怎么办

官方的 API 错误页使用 api_error、service_unavailable、deadline_exceeded 这样的小写名称，页面里没有502，也没有「error 13」。网上常见的 500 INTERNAL、UNAVAILABLE 这类大写名称，也没有出现在这一页里。所以这两种报错没有官方的逐条解释，建议这样查：

图：本站根据 Gemini API 排查页 整理的示意图

1. 看官方状态页 aistudio.google.com/status，确认是不是官方在处理事件；
2. 502 在 HTTP 里通常表示网关或中间代理收到了上游的无效响应，所以在你和 Google 之间还有代理、网关或第三方中转的话，先绕开它直接请求官方地址试试；
3. 把它当作暂时性错误处理：指数退避重试，设置最大次数；
4. 用的是第三方工具或客户端时，换一个客户端或更新版本再试，并查看工具自己的日志；
5. 持续出现，保存请求 ID 等信息，向官方反馈。

常见问题

Q：Gemini 网页或 App 里的报错呢？

那是另一类，见 /guides/gemini-error-messages-table 和 /guides/gemini-down-check-status-page。

Q：429 是不是一定是我用多了？

官方把 429 分成三种代码，只有看到 quota_exceeded 才是日配额用完，其他两种是短时间内太快，等一等就好。

Q：需要 Google 账号怎么办？

本站有 Google 账号相关服务，具体以页面说明为准。

参考资料

• Gemini API 错误 — https://ai.google.dev/gemini-api/docs/api-errors
• Gemini API 排查 — https://ai.google.dev/gemini-api/docs/troubleshooting
• Google AI Studio 状态页 — https://aistudio.google.com/status