本指南概述了您可能会从 API and our 官方 Python 库。概述中提到的每个错误代码都有相应的专门章节，提供了进一步的指导。
| 代码 | 概览 |
|---|
| 401 - 无效的身份验证 | Cause: 无效的身份验证
Solution: 请确保使用了正确的 API 密钥 和请求组织。 |
| 401 - 提供了不正确的 API 密钥 | Cause: 请求使用的 API 密钥不正确。
Solution: 请确保使用的 API 密钥正确，清除您的浏览器缓存，或者 生成一个新密钥. |
| 401 - 您必须是组织成员才能使用该 API | Cause: 您的账号不属于任何组织。
Solution: 请联系我们将您添加到新组织，或请您的组织管理员 邀请您加入组织. |
| 401 - IP 未授权 | Cause: 您的请求 IP 与您的项目或组织配置的 IP 允许列表不匹配。
Solution: 请从正确的 IP 发送请求，或更新您的 IP 允许列表设置. |
| 403 - 不受支持的国家、地区或领土 | Cause: 您正在从不受支持的国家、地区或领土访问 API。
Solution: 请参阅 此页面 for more information. |
| 429 - 已达到请求速率限制 | Cause: 您的请求发送速度过快。
Solution: 请放缓请求。阅读 速率限制指南. |
| 429 - 您已超出当前配额，请检查您的套餐和账单详情 | Cause: 您的额度已用尽或已达到每月最高消费限额。
Solution: 购买更多额度 or learn how to 提高您的限额. |
| 500 - 服务器在处理您的请求时发生错误 | Cause: 我们的服务器出现了问题。
Solution: 请在短暂等待后重试您的请求，如果问题仍然存在，请联系我们。请查看 状态页. |
| 503 - 引擎当前负载过高，请稍后重试 | Cause: 我们的服务器当前流量较高。
Solution: 请在短暂等待后重试您的请求。 |
| 503 - 请求过快 | Cause: 您的请求速率突然增加，影响了服务的可靠性。
Solution: 请将请求速率降至原有水平，保持该速率至少 15 分钟，然后再逐渐提高。 |
如果你正在使用 Responses API WebSocket 模式，您可能会遇到以下额外错误：
previous_response_not_found： previous_response_id 无法从可用状态中解析。请使用完整的输入上下文重试，并 previous_response_id 进行上传，并将其设置为 null.websocket_connection_limit_reached：连接达到 60 分钟的限制。请建立一个新的 WebSocket 连接并继续。
此错误消息表明您的身份验证凭据无效。这可能有以下几个原因：
- 您正在使用已撤销的 API 密钥。
- 您使用的 API 密钥与分配给请求组织或项目的密钥不一致。
- 您使用的 API 密钥没有调用该端点所需的权限。
要解决此错误，请按照以下步骤操作：
- 请检查您在请求头中是否使用了正确的 API 密钥和组织 ID。您可以在以下位置找到您的 API 密钥和组织 ID： 您的账户设置 或者您可以在以下位置找到与特定项目相关的密钥 通用设置 通过选择相应的项目。
- 如果您不确定 API 密钥是否有效，您可以 生成一个新密钥。请务必在请求中使用新的 API 密钥替换旧密钥，并遵循我们的 最佳实践指南.
此错误消息表明您在请求中使用的 API 密钥不正确。这可能有以下几个原因：
- 您的 API 密钥中存在拼写错误或多余空格。
- 您正在使用属于其他组织或项目的 API 密钥。
- 您正在使用已被删除或停用的 API 密钥。
- 本地可能缓存了旧的、已撤销的 API 密钥。
要解决此错误，请按照以下步骤操作：
- 请尝试清除浏览器的缓存和 Cookie，然后重试。
- 请检查您的请求头中是否使用了正确的 API 密钥。
- 如果您不确定 API 密钥是否正确，可以 生成一个新密钥。请务必在您的代码库中替换旧的 API 密钥，并遵循我们的 最佳实践指南.
此错误消息表明您的账户不属于任何组织。这可能由以下几种原因导致：
- 您已离开或被移出之前的组织。
- 您已离开或被移出之前的项目。
- 您的组织已被删除。
要解决此错误，请按照以下步骤操作：
- 如果您已离开或被移出之前的组织，可以申请新的组织，或受邀请加入现有的组织。
- 要申请新的组织，请通过 help.openai.com 联系我们
- 现有组织的所有者可以通过以下页面邀请您加入他们的组织： 团队页面 或者可以从以下页面创建新项目： 设置页面
- 如果您已离开或被移出之前的项目，可以要求组织或项目所有者将您重新添加到该项目中，或者创建一个新项目。
此错误消息表明您已达到 API 分配的速率限制。这意味着您在短时间内提交了过多的 Token 或请求，超出了允许的请求数量。这可能由以下几种原因导致：
- 您正在使用频繁或并发发出请求的循环或脚本。
- 您正在与其他用户或应用程序共享 API 密钥。
- 您正在使用具有较低速率限制的免费套餐。
- 您已达到项目中设定的限制
要解决此错误，请按照以下步骤操作：
- 请控制请求频率，避免进行不必要或冗余的调用。
- 如果您正在使用循环或脚本，请确保实现退避机制或重试逻辑，以遵循速率限制和响应头。您可以在此阅读更多关于我们的速率限制策略和最佳实践： 速率限制指南.
- 如果您与其他用户共享组织，请注意限制是按组织而非按用户施加的。建议检查团队其他成员的使用情况，因为这部分也会计入限制。
- 如果您正在使用免费或低级别套餐，请考虑升级到提供更高速率限制的按量付费套餐。您可以在我们的以下页面比较各套餐的限制： 速率限制指南.
- 请联系您的组织所有者，以提升项目的速率限制
429 - 您已超出当前配额，请检查您的套餐和账单详情
此错误消息表明您已达到每月的 使用限制 表示 API 已达到限制，或者您的预付费额度已用完。您可以在“限制”页面查看最大使用限制： limits 页面。这可能是由于多种原因造成的，例如：
- 您正在使用消耗大量额度或 token 的高流量或复杂服务。
- 您的组织每月预算相对于其使用量设置得过低。
- 您的项目每月预算相对于其使用量设置得过低。
要解决此错误，请按照以下步骤操作：
- 请检查您的 当前使用量 与您账户的 限制进行比较.
- 如果您使用的是免费套餐，请考虑 升级到付费套餐 to get higher limits.
- 请联系您的组织所有者，以提高您项目的预算。
此错误消息表明我们的服务器当前流量过高，暂时无法处理您的请求。出现这种情况的原因可能包括：
- 对我们服务的需求突然激增或猛增。
- 我们的服务器正在进行计划内或计划外的维护或更新。
- 我们的服务器出现了意外或不可避免的中断或事故。
要解决此错误，请按照以下步骤操作：
- 请在短暂等待后重试您的请求。我们建议使用指数退避策略，或使用遵循响应头和速率限制的重试逻辑。您可以阅读有关我们速率限制的 最佳实践.
- 查看我们的 状态页 以获取有关我们服务和器的任何更新或公告。
- 如果在合理的时间后您仍然遇到此错误，请联系我们以获取进一步的帮助。对于给您带来的任何不便，我们深表歉意，并感谢您的耐心等待与理解。
此错误可能发生在所有 OpenAI 用户共享的按量付费 (Pay-As-You-Go) 模型上。这表明您的流量显著增加，导致模型过载，并触发了临时限流以维持服务的稳定性。
要解决此错误，请按照以下步骤操作：
- 将您的请求速率降低到原有水平，保持稳定至少 15 分钟，然后再逐渐提升。
- 保持一致的流量模式，以最大程度降低被限流的可能性。如果您的请求量保持稳定，您应该很少会遇到此错误。
- 考虑升级至 规模层级 以获得有保障的容量和性能，确保在高峰需求期间具有更可靠的访问能力。
| 类型 | 概览 |
|---|
| APIConnectionError | Cause: 连接到我们的服务时出现问题。
Solution: 请检查您的网络设置、代理配置、SSL 证书或防火墙规则。 |
| APITimeoutError | Cause: 请求超时。
Solution: 请在短暂等待后重试您的请求，如果问题持续存在，请联系我们。 |
| AuthenticationError | Cause: 您的 API 密钥或令牌无效、已过期或已被撤销。
Solution: 请检查您的 API 密钥或令牌，确保其正确且处于激活状态。您可能需要从您的账户控制台生成一个新的密钥或令牌。 |
| BadRequestError | Cause: 您的请求格式不正确，或者缺少某些必填参数，例如令牌或输入内容。
Solution: 错误消息应该会提示您具体的错误。请查阅您正在调用的特定 API 方法的 文档 ，并确保您发送的参数有效且完整。您可能还需要检查请求数据的编码、格式或大小。 |
| ConflictError | Cause: 资源已被其他请求更新。
Solution: 请尝试再次更新该资源，并确保没有其他请求正在尝试更新它。 |
| InternalServerError | Cause: 我们的系统出现问题。
Solution: 请在短暂等待后重试您的请求，如果问题持续存在，请联系我们。 |
| NotFoundError | Cause: 请求的资源不存在。
Solution: 请确保您使用了正确的资源标识符。 |
| PermissionDeniedError | Cause: 您没有访问所请求资源的权限。
Solution: 请确保您使用了正确的 API 密钥、组织 ID 和资源 ID。 |
| RateLimitError | Cause: 您已达到分配的速率限制。
Solution: 请控制您的请求频率。在我们的 速率限制指南. |
| UnprocessableEntityError | Cause: 尽管格式正确，但无法处理该请求。
Solution: 请重试该请求。 |
An APIConnectionError 表示您的请求无法到达我们的服务器或建立安全连接。这可能是由于网络问题、代理配置、SSL 证书或防火墙规则引起的。
如果您遇到 APIConnectionError，请尝试以下步骤：
- 请检查您的网络设置，确保您拥有稳定且快速的网络连接。您可能需要切换到其他网络，使用有线连接，或减少占用带宽的设备或应用程序数量。
- 请检查您的代理配置，确保其与我们的服务兼容。您可能需要更新代理设置、使用其他代理或完全绕过代理。
- 请检查您的 SSL 证书，确保它们有效且是最新的。您可能需要安装或更新证书、使用其他证书颁发机构或禁用 SSL 验证。
- 请检查您的防火墙规则，确保它们没有阻止或过滤我们的服务。您可能需要修改防火墙设置。
- 如果适用，请检查您的容器是否具有发送和接收流量的正确权限。
- 如果问题仍然存在，请查看我们的持续性错误后续步骤部分。
A APITimeoutError 错误表示您的请求耗时过长，服务器已关闭连接。这可能是由于网络问题、我们的服务负载过重，或者请求过于复杂需要更多处理时间所致。
如果您遇到 APITimeoutError 错误，请尝试以下步骤：
- 等待几秒钟然后重试您的请求。有时，网络拥堵或我们的服务负载可能会减轻，您的请求可能会在第二次尝试时成功。
- 请检查您的网络设置，确保您拥有稳定且快速的网络连接。您可能需要切换到其他网络，使用有线连接，或减少占用带宽的设备或应用程序数量。
- 如果问题仍然存在，请查看我们的持续性错误后续步骤部分。
An AuthenticationError 表示您的 API 密钥或令牌无效、已过期或已被撤销。这可能是由于拼写错误、格式错误或安全漏洞引起的。
如果您遇到 AuthenticationError，请尝试以下步骤：
- 请检查您的 API 密钥或令牌，确保其正确且处于活动状态。您可能需要从 API 密钥控制面板生成新密钥，确保没有多余的空格或字符，或者在拥有多个密钥或令牌时使用其他的密钥或令牌。
- 请确保您遵循了正确的格式。
An BadRequestError （前身为 InvalidRequestError）表示你的请求格式不正确，或者缺少某些必需的参数（例如令牌或输入）。这可能是由于拼写错误、格式错误或代码中的逻辑错误导致的。
如果您遇到 BadRequestError，请尝试以下步骤：
- 请仔细阅读错误信息并确定具体的错误原因。错误信息通常会提示你哪个参数无效或缺失，以及期望的值或格式。
- 查阅 API 参考 关于你正在调用的特定 API 方法的文档，确保你发送了有效且完整的参数。你可能需要检查参数的名称、类型、值和格式，并确保它们与文档一致。
- 检查请求数据的编码、格式或大小，确保它们与我们的服务兼容。你可能需要将数据编码为 UTF-8，将数据格式化为 JSON，或者在数据过大时进行压缩。
- 使用 Postman 或 curl 等工具测试你的请求，确保其按预期工作。你可能需要调试代码并修复请求逻辑中的任何错误或不一致之处。
- 如果问题仍然存在，请查看我们的持续性错误后续步骤部分。
An InternalServerError 表示我们在处理你的请求时内部出现了问题。这可能是由于临时错误、Bug 或系统宕机造成的。
对于由此带来的任何不便，我们深表歉意，我们正在全力以赴尽快解决所有问题。你可以 查看我们的系统状态页面 for more information.
如果您遇到 InternalServerError，请尝试以下步骤：
- 请等待几秒钟然后重试你的请求。有时问题可能会很快解决，你的请求可能会在第二次尝试时成功。
- 查看我们的状态页面，了解可能影响我们服务的正在发生的事件或维护。如果存在活跃事件，请关注相关更新，等待问题解决后再重试你的请求。
- 如果问题持续存在，请查看我们的“持续错误后续步骤”部分。
我们的支持团队将调查此问题，并尽快给你回复。请注意，由于需求量很大，我们的支持队列等待时间可能较长。你也可以 在我们的社区论坛发帖 但务必省略任何敏感信息。
A RateLimitError 表示您已达到分配的速率限制。这意味着您在给定时间内发送了过多的 token 或请求，我们的服务已暂时阻止您发送更多内容。
我们施加速率限制，以确保公平高效地利用我们的资源，并防止服务被滥用或过载。
如果您遇到 RateLimitError，请尝试以下步骤：
- 减少发送的 token 或请求数量，或降低发送频率。您可能需要降低请求的频率或数量、对 token 进行批量处理，或者实现指数退避。您可以阅读我们的 速率限制指南 for more details.
- 等待速率限制重置（一分钟）后重试您的请求。错误信息应该能让您了解自己的使用速率和允许的使用量。
- 您还可以从账户控制台检查您的 API 使用统计数据。
如果问题持续存在， 通过聊天联系我们的支持团队 并向他们提供以下信息：
- 您当时使用的模型
- 您收到的错误信息和错误代码
- 您发送的请求数据和请求头
- 您发送请求的时间戳和时区
- 任何其他可能有助于我们诊断问题的相关信息
我们的支持团队将调查此问题，并尽快给你回复。请注意，由于需求量很大，我们的支持队列等待时间可能较长。你也可以 在我们的社区论坛发帖 但务必省略任何敏感信息。
我们建议您以编程方式处理 API 返回的错误。为此，您可能需要使用类似下面的代码片段：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import openai
from openai import OpenAI
client = OpenAI()
try:
response = client.chat.completions.create(
prompt="Hello world",
model="gpt-4o-mini"
)
except openai.APIError as e:
print(f"OpenAI API returned an API Error: {e}")
pass
except openai.APIConnectionError as e:
print(f"Failed to connect to OpenAI API: {e}")
pass
except openai.RateLimitError as e:
print(f"OpenAI API request exceeded rate limit: {e}")
pass
