本指南可帮助您诊断和解决调用 Gemini API 时发生的常见问题。如果您遇到 API 密钥问题，请确保您已根据 API 密钥设置指南正确设置了 API 密钥。
错误代码
下表列出了您可能遇到的常见错误代码，以及关于相应原因和问题排查步骤的说明：
| HTTP 代码 | 状态 | 说明 | 解决方案 |
| 400 | INVALID_ARGUMENT | 请求正文格式错误。 | 如需了解请求格式、示例和支持的版本，请参阅 API 参考文档。如果将新版 API 中的功能与旧版端点搭配使用，可能会导致错误。 |
| 403 | PERMISSION_DENIED | 您的 API 密钥不具备所需的权限。 | 请检查您的 API 密钥是否已设置且拥有适当的访问权限。 |
| 404 | NOT_FOUND | 找不到所请求的资源。 | 检查请求中的所有参数对您的 API 版本是否有效。 |
| 429 | RESOURCE_EXHAUSTED | 您已超出速率限制。 | 确保未超出模型的速率限制。根据需要申请增加配额。 |
| 500 | INTERNAL | Google 方面发生了意外错误。 | 请稍等片刻，然后重试您的请求。如果重试后问题仍然存在，请使用 Google AI Studio 中的发送反馈按钮报告该问题。 |
| 503 | UNAVAILABLE | 服务可能暂时过载或关闭。 | 请稍等片刻，然后重试您的请求。如果重试后问题仍然存在，请使用 Google AI Studio 中的发送反馈按钮报告该问题。 |
检查 API 调用是否存在模型参数错误
确保您的模型参数在以下值范围内：
| 模型参数 | 值（范围） |
| 候选人数量 | 1-8（整数） |
| 温度 | 0.0-1.0 |
| 输出令牌数量上限 |
使用 get_model (Python) 确定所用模型的令牌数量上限。 |
| TopP | 0.0-1.0 |
除了检查参数值之外，请确保您使用的是正确的 API 版本（例如/v1 或 /v1beta）和模型，以支持您需要的功能。例如，如果某个功能处于 Beta 版阶段，它将仅在 /v1beta API 版本中提供。
检查您的模型是否正确
确保您使用的是受支持的模型。使用 list_models (Python) 获取所有可用的模型。
安全问题
如果您发现提示因 API 调用中的安全设置而被屏蔽，请根据您在 API 调用中设置的过滤条件检查相应提示。
如果您看到 BlockedReason.OTHER，则表示查询或响应可能违反服务条款或不受支持。
改进模型输出
若要获得更优质的模型输出，不妨尝试编写更多结构化提示。提示设计简介页面介绍了一些基本概念、策略和最佳实践，旨在帮助您上手。
如果您有数百个良好输入/输出对的示例，还可以考虑进行模型调整。
了解令牌限制
使用 ModelService API 获取有关模型的其他元数据，包括输入和输出令牌限制。
如需获取提示所使用的令牌，请将 countMessageTokens 用于聊天模型，将 countTextTokens 用于文本模型。
已知问题
- 对 Google AI Studio 的移动支持：虽然您可以在移动设备上打开网站，但该网站还没有针对小屏幕进行优化。
- 该 API 仅支持英语。以不同语言提交提示可能会导致产生意外甚至被阻止的响应。如需了解相关更新，请参阅支持的语言。
提交 bug
在 GitHub 中提交问题，以便提问或提交功能请求或 bug。