错误处理
常见 API 错误码及处理方法，帮助您快速定位和解决问题
错误处理的重点不只是记住状态码
对于真实接入来说，API 报错页面最重要的作用，不只是告诉你 400、401、429 分别代表什么，而是帮助你建立一套排查顺序。只有这样，当服务进入正式环境后，你才能在报错发生时更快定位到底是参数问题、权限问题、配额问题还是服务短暂波动。
很多团队的痛点不是不会看报错，而是日志不完整、上下文不统一、重试逻辑不清晰。因此一个成熟的错误处理页，应该同时解释错误码、排查路径、重试策略和最少需要记录哪些日志字段。
HTTP 状态码
请求参数无效或缺失
解决方案: 检查请求体格式和参数值
API Key 无效或过期
解决方案: 检查 API Key 是否正确
没有调用该模型的权限
解决方案: 确认 API Key 已启用该模型
请求的模型不存在
解决方案: 检查模型名称拼写
超出速率限制或配额
解决方案: 等待后重试或升级计划
服务器内部错误
解决方案: 稍后重试
服务暂时不可用
解决方案: 稍后重试
Python 错误处理示例
import google.generativeai as genai
from google.api_core.exceptions import *
try:
response = model.generate_content("Hello")
except InvalidArgument as e:
print(f"参数错误: {e}")
except Unauthenticated as e:
print(f"认证失败: {e}")
except PermissionDenied as e:
print(f"权限不足: {e}")
except ResourceExhausted as e:
print(f"配额已用完: {e}")
# 实现指数退避重试
except GoogleAPIError as e:
print(f"API 错误: {e}")推荐排查顺序
- 1. 先看状态码和错误名称，判断是参数、鉴权还是限流问题。
- 2. 检查模型名称、请求体字段和必填参数是否正确。
- 3. 确认 API Key、权限、配额和调用来源配置。
- 4. 若为 5xx 或 UNAVAILABLE，优先考虑短暂重试和降级。
建议保留的日志字段
- 请求时间、请求 ID、模型名称。
- 调用入口、用户或任务标识。
- 状态码、错误名称、原始错误消息。
- 是否重试、重试次数和最终结果。
重试策略建议
对于 429、500、503 这类错误，通常适合使用指数退避重试，并增加随机抖动，避免同一时间大量请求再次打满服务。
对于 400、401、403、404 这类错误，重试通常没有意义，因为它们更可能是参数、模型名、权限或调用方式本身存在问题，应优先回到请求配置和接入文档排查。
如果你的产品面向终端用户，建议在前台给出更可理解的提示，例如“当前请求过于频繁，请稍后再试”，而不是直接暴露原始错误。
相关页面
最容易被忽略的错误处理问题
- 只在控制台打印报错，却没有记录请求上下文。
- 把所有异常都统一重试，导致参数错误也被反复调用。
- 前台直接暴露原始错误文本，影响用户体验和安全性。
- 没有区分临时服务波动和接入配置错误。
更成熟的处理目标
- 开发者能快速定位问题来源，而不是靠猜。
- 系统能对可恢复错误自动重试，对不可恢复错误快速失败。
- 前台用户能看到友好提示，而不是技术细节。
- 日志、报警和排查路径能支持正式上线后的持续运营。
错误处理 在 Gemini 接入流程中的作用
错误处理 更适合放在完整接入链路中去理解，而不是孤立阅读。对于 Gemini API 来说，开发者通常不会只靠一页文档完成所有工作，而是需要在快速入门、认证、模型选择、错误处理、安全控制和计费规则之间不断来回对照。
当前页面所覆盖的内容，更多是在帮助你补齐某一个关键环节。常见 API 错误码及处理方法，帮助您快速定位和解决问题 如果这部分理解不够充分，前期也许能跑通，但到了业务扩容、多人协作和生产环境阶段，问题往往会逐渐放大。
阅读这类页面时，最好同时思考自己的项目状态：你是处于试验阶段、正式接入阶段，还是正在做稳定性补强。不同阶段关注的重点不同，页面里的同一段内容，在不同时间点的价值也会不同。
如果你希望当前页面的内容真正服务实际开发，建议边读边确认自己的模型、语言、部署环境和权限策略。这样再回看相关链接时，会更容易形成可执行的开发方案，而不是停留在概念层。
阅读 错误处理 时可以顺手确认的细节
很多技术主题看起来像局部问题，但一旦进入真实项目，就会和模型选择、日志记录、部署环境和调用成本产生连锁关系。因此，单页文档越是基础，越值得结合整体流程去看。
如果当前主题涉及 SDK、接口格式、异常状态或鉴权方式，最好马上用自己的项目场景试着对应一遍。这样可以更快发现还有哪些缺口需要回到其他文档补齐。
对于正式商用场景，建议把文档中的默认用法进一步改造成符合自己环境的实现，例如更明确的重试策略、密钥隔离和监控记录。这样更接近长期可维护的接入方式。
看上下游关系
当前页面通常只是开发链路中的一个节点，前后内容往往同样关键。
看实际环境
浏览器试验、服务端接入和企业环境，对同一主题的要求并不完全相同。
看后续维护
越早把异常处理和权限边界想清楚，后面越容易稳定扩展。