借助本指南，您可以诊断和解决 您需要调用 Gemini API。大体上讲，您可能会遇到 Gemini API 后端服务或客户端 SDK。我们的客户端 SDK 已在以下代码库中开源：
- generative-ai-python
- generative-ai-js
- generative-ai-android
- generative-ai-swift
- generative-ai-dart
- generative-ai-go
如果您遇到 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 Studio 中的发送反馈按钮报告该问题。 |
| 503 | UNAVAILABLE | 服务可能暂时过载或关闭。 | 服务的容量暂时用尽。 | 暂时切换到其他模型（例如从 Gemini 1.5 Pro 切换到 Gemini 1.5 Flash），看看能否正常运行。或者，稍后重试您的请求。如果重试后问题仍然存在，请使用 Google AI Studio 中的发送反馈按钮报告该问题。 |
| 504 | DEADLINE_EXCEEDED | 服务无法在截止期限内完成处理。 | 你的提示（或上下文）太大，无法及时处理。 | 设置较长的“超时”以免发生此错误。 |
Python 客户端 SDK 错误代码
下表列出了常见的 Python 客户端 SDK 错误 及其原因的解释说明：
| 异常/错误类型 | 类 | 说明 |
|---|---|---|
| BlockedPromptException | google.generativeai.types.BlockedPromptException | 出于安全原因，该提示已被屏蔽。 |
| BrokenResponseError | google.generativeai.types.BrokenResponseError | 流式传输响应已损坏。在访问需要完整响应的内容（例如聊天记录）时引发。查看堆栈轨迹中提供的错误详情。 |
| IncompleteIterationError | google.generativeai.types.IncompleteIterationError | 访问需要完整 API 响应但流式响应尚未完全迭代的内容时引发。对响应对象调用 resolve() 以使用迭代器。 |
| StopCandidateException | google.generativeai.types.StopCandidateException | 该 API 给出了异常 finish_reason 的响应。请查看原因，获取关于如何继续操作的建议。 |
| PermissionDenied | google.api_core.exceptions.PermissionDenied | 您无权使用所请求的资源（例如模型）。 |
| ResourceExhausted | google.api_core.exceptions.ResourceExhausted | 您的配额已用尽。请稍后重试。请考虑设置自动重试来处理这些错误。 |
| AlreadyExists | google.api_core.exceptions.AlreadyExists | 已存在具有相同 ID 的已调参模型。对新模型进行调参时，请指定唯一的模型 ID。 |
| InvalidArgument | google.api_core.exceptions.InvalidArgument | 参数无效。例如，文件过大，超出了载荷大小限制。另一个事件提供了无效的 API 密钥。 |
| DefaultCredentialsError | google.auth.exceptions.DefaultCredentialsError | 身份验证失败。请仔细检查您的 API 密钥，然后重试。 |
| RetryError | google.api_core.exceptions.RetryError | 使用不支持 gRPC 的代理时可能会引起此错误。请尝试将 REST 传输与 genai.configure(..., transport="rest") 搭配使用。 |
检查您的 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 开发者论坛上的讨论 。