本指南可帮助您诊断和解决调用 Gemini API 时出现的常见问题。您可能会遇到 Gemini API 后端服务或客户端 SDK 方面的问题。我们的客户端 SDK 在以下代码库中以开源形式提供：
如果您遇到 API 密钥问题，请确保您已按照 API 密钥设置指南正确设置 API 密钥。
Gemini API 后端服务错误代码
下表列出了您可能会遇到的常见后端错误代码，以及相应原因的说明和问题排查步骤：
| HTTP 代码 | 状态 | 说明 | 示例 | 解决方案 |
| 400 | INVALID_ARGUMENT | 请求正文格式有误。 | 您的请求中存在拼写错误或缺少必填字段。 | 如需了解请求格式、示例和支持的版本，请参阅 API 参考文档。将较新 API 版本中的功能与较旧的端点搭配使用可能会导致错误。 |
| 400 | FAILED_PRECONDITION | Gemini API 免费层级不适用于您所在的国家/地区。请在 Google AI Studio 中为您的项目启用结算功能。 | 您在不支持免费层级的区域中发出请求，并且您尚未在 Google AI Studio 中为项目启用结算功能。 | 如需使用 Gemini API，您需要使用 Google AI Studio 设置付费方案。 |
| 403 | PERMISSION_DENIED | 您的 API 密钥没有所需的权限。 | 您使用的 API 密钥有误；您尝试在不进行适当身份验证的情况下使用经过优化的模型。 | 检查您的 API 密钥是否已设置且具有适当的访问权限。请务必完成适当的身份验证，才能使用经过调优的模型。 |
| 404 | NOT_FOUND | 找不到所请求的资源。 | 我们未找到您请求中提及的图片、音频或视频文件。 | 检查请求中的所有参数是否对您的 API 版本有效。 |
| 429 | RESOURCE_EXHAUSTED | 您已超出速率限制。 | 您通过免费层级 Gemini API 每分钟发送的请求过多。 | 确保您未超出模型的速率限制。如有必要，请申请增加配额。 |
| 500 | INTERNAL | Google 端出现了意外错误。 | 您的输入上下文过长。 | 减少输入上下文或暂时切换到其他模型（例如，从 Gemini 1.5 Pro 切换到 Gemini 1.5 Flash），看看能否解决问题。或者稍等片刻，然后重试您的请求。如果重试后问题仍然存在，请使用 Google AI 工作室中的发送反馈按钮进行报告。 |
| 503 | UNAVAILABLE | 服务可能暂时过载或关闭。 | 服务暂时超载。 | 暂时切换到其他模型（例如，从 Gemini 1.5 Pro 切换到 Gemini 1.5 Flash），看看能否正常运行。或者稍等片刻，然后重试您的请求。如果重试后问题仍然存在，请使用 Google AI 工作室中的发送反馈按钮进行报告。 |
| 504 | DEADLINE_EXCEEDED | 服务无法在截止时间内完成处理。 | 您的问题（或上下文）太大，无法及时处理。 | 请在客户端请求中设置较长的“超时”值，以避免此错误。 |
检查 API 调用是否存在模型参数错误
确保您的模型参数在以下值范围内：
| 模型参数 | 值（范围） |
| 候选数量 | 1-8（整数） |
| 温度 | 0.0-1.0 |
| 输出令牌数量上限 |
使用 get_model (Python) 确定您所用模型的词元数上限。
|
| TopP | 0.0-1.0 |
除了检查参数值外，还应确保您使用的是正确的 API 版本（例如/v1 或 /v1beta）和支持您所需功能的型号。例如，如果某项功能处于 Beta 版阶段，则该功能仅在 /v1beta API 版本中提供。
检查您是否使用的是正确的型号
确保您使用的是模型页面上列出的受支持的模型。
安全问题
如果您发现某个提示因 API 调用中的安全设置而被屏蔽，请根据您在 API 调用中设置的过滤条件检查该提示。
如果您看到 BlockedReason.OTHER，则表示相应查询或响应可能违反了服务条款或不受支持。
背诵问题
如果您发现模型因 RECITATION 原因而停止生成输出，则表示模型输出可能与某些数据相似。如需解决此问题，请尝试使提示 / 上下文尽可能唯一，并使用更高的温度。
改进模型输出
如需获得更高质量的模型输出，请尝试编写更结构化的提示。提示工程指南页面介绍了一些基本概念、策略和最佳实践，可帮助您开始使用。
如果您有数百个良好的输入/输出对示例，还可以考虑模型调优。
了解令牌限制
请仔细阅读我们的令牌指南，更好地了解如何计算令牌数及其限制。
已知问题
- 该 API 仅支持部分语言。以不受支持的语言提交提示可能会产生意外的回答，甚至会导致回答被屏蔽。如需了解最新信息，请参阅支持的语言。
提交 bug
如果您有任何疑问，欢迎加入 Google AI 开发者论坛讨论。