本指南概述了您在使用 API 和我们的官方 Python 库 时可能遇到的错误代码。概览中提到的每个错误代码都有专门的章节，提供进一步指导。
代码 概览 400 - service_tier 参数无效 原因： 项目不允许使用请求指定或最终确定的服务层级。解决方法： 将 service_tier 设为项目允许的层级，或在项目设置 中更新允许使用的服务层级。401 - 身份验证无效 原因： 身份验证无效。解决方法： 确保使用了正确的 API 密钥 ，并指定了正确的请求所属组织。401 - 提供的 API 密钥不正确 原因： 请求使用的 API 密钥不正确。解决方法： 确保使用的 API 密钥正确，清除浏览器缓存，或生成新密钥 。401 - 您必须是某个组织的成员才能使用 API 原因： 您的账户不属于任何组织。解决方法： 联系我们，让我们将您加入新组织，或请您的组织管理员邀请您加入组织 。401 - IP 未获授权 原因： 您的请求 IP 不在项目或组织配置的 IP 允许列表中。解决方法： 从正确的 IP 发送请求，或更新您的 IP 允许列表设置 。403 - 不支持的国家、地区或属地 原因： 您正在从不受支持的国家、地区或属地访问 API。解决方法： 请参阅此页面 了解更多信息。429 - 额度余额已用尽 代码： credit_balance_exhausted 原因： 您的组织已无剩余预付额度。解决方法： 充值额度 以继续使用 API。429 - 已达到请求速率限制 原因： 您发送请求的速度过快。解决方法： 控制请求频率，并在响应包含 Retry-After 标头时按其指示操作。请阅读速率限制指南 。429 - 请降低请求速率 类型： rate_limit_error 代码： slow_down 原因： 您的请求速率增长过快。解决方法： 如果响应包含 Retry-After 标头，请按其指示操作。降低请求速率，然后逐步提高。429 - 已达到组织支出限额 代码： organization_spend_limit_exceeded 原因： 您的组织已达到强制执行的支出限额。解决方法： 提高或取消您的组织支出限额 。429 - 已达到项目支出限额 代码： project_spend_limit_exceeded 原因： 您的项目已达到强制执行的支出限额。解决方法： 在项目设置 中提高或取消支出限额。429 - 已达到组织用量上限 代码： organization_usage_limit_exceeded 原因： 您的组织已达到 OpenAI 分配的用量上限。解决方法： 申请提高获批的用量上限 ，或联系支持团队 。500 - 服务器在处理您的请求时发生错误 原因： 我们的服务器出现问题。解决方法： 稍等片刻后重试请求，如果问题仍然存在，请联系我们。请查看状态页面 。503 - 模型暂时过载 类型： service_unavailable_error 代码： server_is_overloaded 原因： 请求的模型暂时过载。解决方法： 如果响应包含 Retry-After 标头，请先按其指示操作，再重试请求。
对于账单相关错误，请检查 error.code 以确定具体原因。表示较宽泛错误类别的 error.type 仍可能为 insufficient_quota。
遇到账单、支出或配额错误时，重试并不能恢复 API 访问。请先更新相关额度或限额，再发送请求。
如果您使用的是 Responses API WebSocket 模式 ，还可能遇到以下错误：
previous_response_not_found：无法根据可用状态解析 previous_response_id。请提供完整的输入上下文，将 previous_response_id 设为 null，然后重试。websocket_connection_limit_reached：连接已达到 60 分钟的时长限制。请建立新的 WebSocket 连接后继续。
400 - service_tier 参数无效 当请求选择或最终确定的服务层级不被项目允许时，API 会返回 invalid_request_error 错误，消息为 "Invalid service_tier argument: The requested service tier is not allowed for this project."，并将 error.param 设为 service_tier。
项目限制适用于 default、flex 和 priority 服务层级。fast 服务层级按 priority 进行评估。如果请求省略了 service_tier 或将其设为 auto，而最终确定的层级不被允许，也可能返回此错误。规模层级仍不受此项目策略约束。
要解决此错误：
在项目设置 中检查允许使用的服务层级。
将 service_tier 设为项目允许的层级。
如果请求使用 auto 或省略了 service_tier，请更新项目设置，以允许使用最终确定的层级。
401 - 身份验证无效 此错误消息表示您的身份验证凭据无效。可能的原因有多种，例如：
您使用的 API 密钥已被撤销。
您使用的 API 密钥与分配给请求所属组织或项目的密钥不同。
您使用的 API 密钥不具备调用该端点所需的权限。
要解决此错误，请按以下步骤操作：
检查请求标头中是否使用了正确的 API 密钥和组织 ID。您可以在账户设置 中找到 API 密钥和组织 ID，也可以选择所需的项目，在常规设置 中找到该项目的相关密钥。
如果您不确定 API 密钥是否有效，可以生成新密钥 。请务必将请求中的旧 API 密钥替换为新密钥，并遵循我们的最佳实践指南 。
401 - 提供的 API 密钥不正确 此错误消息表示您在请求中使用的 API 密钥不正确。可能的原因有多种，例如：
您的 API 密钥存在拼写错误或多余的空格。
您使用的 API 密钥属于其他组织或项目。
您使用的 API 密钥已被删除或停用。
本地可能缓存了已被撤销的旧 API 密钥。
要解决此错误，请按以下步骤操作：
尝试清除浏览器的缓存和 Cookie，然后重试。
检查请求头中使用的 API 密钥是否正确。
如果您不确定 API 密钥是否正确，可以生成一个新密钥 。请务必替换代码库中的旧 API 密钥，并遵循我们的最佳实践指南 。
401 - 您必须是组织成员才能使用 API 此错误消息表示您的账户不属于任何组织。可能的原因包括：
您已退出之前的组织，或已被该组织移除。
您已退出之前的项目，或已被该项目移除。
您的组织已被删除。
要解决此错误，请按以下步骤操作：
如果您已退出之前的组织或被该组织移除，可以申请创建新组织，或通过邀请加入现有组织。
如需申请创建新组织，请通过 help.openai.com 联系我们。
现有组织的所有者可以通过团队页面 邀请您加入其组织，也可以通过设置页面 创建新项目。
如果您已退出之前的项目或被该项目移除，可以请组织或项目所有者将您加入该项目，或创建新项目。
429 - 额度余额已用尽 credit_balance_exhausted 错误表示您所在组织的预付额度余额已用尽。
要恢复 API 访问，请在账单设置中添加额度 。
429 - 已达到请求速率限制 此错误消息表示您已达到分配给您的 API 速率限制。这意味着您在短时间内提交了过多的 Token 或请求，超过了允许的请求数量。可能的原因包括：
您使用的循环或脚本会频繁或并发发送请求。
您正在与其他用户或应用共享 API 密钥。
您使用的是速率限制较低的免费套餐。
您已达到项目设定的限制。
要解决此错误，请按以下步骤操作：
控制请求的发送节奏，避免不必要或重复的调用。
如果响应中包含 Retry-After 头，请至少等待其中指定的时间后再重试。如果没有该头，请使用带随机抖动的指数退避，并限制重试次数。SDK 对服务器指定的较长等待时间的支持因版本和配置而异。详情请参阅我们的速率限制指南 。
如果您与其他用户同属一个组织，请注意，限制以组织为单位，而不是以用户为单位。建议检查团队其他成员的使用情况，因为他们的用量也会计入该限制。
如果您使用的是免费或低档位套餐，可以考虑升级为速率限制更高的按量付费套餐。您可以在我们的速率限制指南 中比较各套餐的限制。
请联系您的组织所有者，提高项目的速率限制。
429 - 请降低请求速率 类型为 rate_limit_error、错误代码为 slow_down 的 429 响应表示，您的请求速率增长过快，超出了服务能够安全处理的范围。即使您的流量未超出每分钟请求数和每分钟 Token 数的限制，也可能出现此错误。
根据经验，当您的流量达到每分钟 100 万个输入 Token（TPM）后，每 15 分钟的增幅应不超过 50%。增长速率限制的具体触发点可能因模型和流量状况而异。
要解决此错误：
如果响应中包含 Retry-After 头，请至少等待其中指定的时间后再重试。如果没有该头，请延长重试间隔，并额外加入一小段随机延迟。
降低请求速率，然后逐步提高。
保持流量平稳，以降低再次出现 slow_down 错误的概率。
如果企业客户的按量付费流量经常触发增长速率限制，可以考虑使用规模层级 ，以便在符合条件的模型上获得更可预测的容量。对于 GPT-5.6 及后续模型，请参阅预留层级 。这些容量选项不能替代上述恢复步骤：响应中包含 Retry-After 时，仍应遵循其要求，并逐步增加流量。
429 - 已达到组织支出限额 organization_spend_limit_exceeded 错误表示您的组织已达到强制执行的每月支出限额 。此限额适用于组织内所有项目的 API 流量。
要恢复 API 访问，请在组织限额设置 中提高或移除此限额。否则，访问将在每月限额重置后恢复。
429 - 已达到项目支出限额 project_spend_limit_exceeded 错误表示您的项目已达到强制执行的每月支出限额 。其他项目可以继续使用，除非这些项目自身的限额或组织限额也已达到。
要恢复 API 访问，请在项目设置 中提高或移除此限额。否则，访问将在每月限额重置后恢复。
429 - 已达到组织用量限额 organization_usage_limit_exceeded 错误表示您的组织已达到 OpenAI 分配的每月用量限额 。此限额与您配置的组织和项目支出限额相互独立。
要恢复 API 访问，请申请提高获批用量限额 ，或联系支持团队 。
503 - 模型暂时过载 类型为 service_unavailable_error、错误代码为 server_is_overloaded 的 503 响应表示，所请求的模型目前没有足够的容量来处理您的请求。
如果响应中包含 Retry-After 头，请至少等待其中指定的时间后再重试。如果没有该头，请延长重试间隔。如果错误持续出现，请查看状态页面 ，确认是否存在尚未解决的故障。
Python 会针对 429 响应抛出 RateLimitError，针对 503 响应抛出 InternalServerError。如果您的错误处理程序此前仅捕获其中一种异常类来处理限流和过载情况，请改为处理这两种异常，并检查 error.code。例如，视频服务过载时，现在返回 503，而此前返回 429。有关各端点的具体变更，请参阅迁移指南 。
类型 概览 APIConnectionError 原因： 连接我们的服务时出现问题。解决方法： 检查您的网络设置、代理配置、SSL 证书或防火墙规则。APITimeoutError 原因： 请求超时。解决方法： 稍等片刻后重试请求；如果问题仍然存在，请联系我们。AuthenticationError 原因： 您的 API 密钥或 Token 无效、已过期或已被撤销。解决方法： 检查您的 API 密钥或 Token，确保其正确且处于有效状态。您可能需要在账户控制面板中生成新的密钥或 Token。BadRequestError 原因： 您的请求格式不正确，或缺少某些必需参数，例如 Token 或输入。解决方法： 错误消息应会指出具体错误。请查阅您所调用的 API 方法的文档 ，确保发送的参数有效且完整。您可能还需要检查请求数据的编码、格式或大小。ConflictError 原因： 该资源已被另一个请求更新。解决方法： 尝试再次更新该资源，并确保没有其他请求正在尝试更新它。InternalServerError 原因： 我们这边出现了问题。解决方法： 稍等片刻后重试请求；如果问题仍然存在，请联系我们。NotFoundError 原因： 请求的资源不存在。解决方法： 确保您使用的资源标识符正确。PermissionDeniedError 原因： 您无权访问请求的资源。解决方法： 确保您使用的 API 密钥、组织 ID 和资源 ID 正确。RateLimitError 原因： 您已达到为您分配的速率限制，或流量增长过快。解决方法： 控制请求发送速率，并在响应包含 Retry-After 时遵循其指示，同时遵守您的重试限制。更多信息，请参阅我们的速率限制指南 。UnprocessableEntityError 原因： 请求格式正确，但无法处理。解决方法： 请重试请求。
APIConnectionError APIConnectionError 表示您的请求无法到达我们的服务器或无法建立安全连接。这可能是由网络问题、代理配置、SSL 证书或防火墙规则导致的。
如果您遇到 APIConnectionError，请尝试以下步骤：
检查您的网络设置，确保互联网连接稳定且快速。您可能需要切换到其他网络、使用有线连接，或减少占用带宽的设备或应用数量。
检查您的代理配置，确保其与我们的服务兼容。您可能需要更新代理设置、使用其他代理，或完全绕过代理。
检查您的 SSL 证书，确保其有效且已及时更新。您可能需要安装或续期证书、使用其他证书颁发机构，或禁用 SSL 验证。
检查您的防火墙规则，确保其未阻止或过滤我们的服务。您可能需要修改防火墙设置。
如果适用，请检查您的容器是否具有发送和接收网络流量所需的权限。
如果问题仍然存在，请参阅“持续出现的错误”部分，了解后续步骤。
APITimeoutError APITimeoutError 错误表示您的请求耗时过长，我们的服务器已关闭连接。这可能是由网络问题、我们的服务负载过高，或请求较为复杂、需要更长的处理时间导致的。
如果您遇到 APITimeoutError 错误，请尝试以下步骤：
等待几秒后重试请求。有时，网络拥堵或我们的服务负载可能会有所缓解，您的请求可能会在第二次尝试时成功。
检查您的网络设置，确保互联网连接稳定且快速。您可能需要切换到其他网络、使用有线连接，或减少占用带宽的设备或应用数量。
如果问题仍然存在，请参阅“持续出现的错误”部分，了解后续步骤。
AuthenticationError AuthenticationError 表示您的 API 密钥或 Token 无效、已过期或已被撤销。这可能是由拼写错误、格式错误或安全事件导致的。
如果您遇到 AuthenticationError，请尝试以下步骤：
检查您的 API 密钥或 Token，确保其正确且处于有效状态。您可能需要在 API 密钥控制台生成新密钥，确保没有多余的空格或字符，或者在拥有多个密钥或 Token 时改用另一个。
确保您使用了正确的格式。
BadRequestError BadRequestError（原名为 InvalidRequestError）表示您的请求格式有误，或缺少某些必需参数，例如 Token 或输入。这可能是由拼写错误、格式错误或代码中的逻辑错误导致的。
如果您遇到 BadRequestError，请尝试以下步骤：
仔细阅读错误消息，确定具体错误。错误消息应指出哪个参数无效或缺失，以及预期的值或格式。
查阅您所调用的具体 API 方法的 API 参考 ，确保发送的参数有效且完整。您可能需要检查参数名称、类型、值和格式，确保其符合文档要求。
检查请求数据的编码、格式或大小，确保其与我们的服务兼容。您可能需要使用 UTF-8 对数据进行编码、将数据格式设为 JSON，或在数据过大时进行压缩。
使用 Postman 或 curl 等工具测试您的请求，确保其按预期运行。您可能需要调试代码，修复请求逻辑中的错误或不一致之处。
如果问题仍然存在，请参阅“持续出现的错误”部分，了解后续步骤。
InternalServerError InternalServerError 表示我们在处理您的请求时出现了问题。这可能是由临时错误、程序缺陷或系统中断导致的。
对于由此带来的不便，我们深表歉意，并正在努力尽快解决问题。您可以查看我们的系统状态页面 ，了解更多信息。
如果您遇到 InternalServerError，请尝试以下步骤：
等待几秒后重试请求。有时，问题可能会很快解决，您的请求可能会在第二次尝试时成功。
查看我们的状态页面，了解是否存在可能影响服务的故障或正在进行的维护。如果有尚未解决的故障，请关注后续更新，待故障解决后再重试请求。
如果问题仍然存在，请参阅“持续出现的错误”部分，了解后续步骤。
我们的支持团队将调查此问题，并尽快回复您。请注意，由于咨询量较大，排队等待支持的时间可能较长。您也可以在我们的社区论坛发帖 ，但务必不要包含任何敏感信息。
RateLimitError RateLimitError 表示您已达到为您分配的速率限制。这意味着您在一定时间内发送了过多的 Token 或请求，我们的服务已暂时阻止您继续发送。
我们设置速率限制，是为了确保资源得到公平、高效的使用，并防止服务被滥用或过载。
如果您遇到 RateLimitError，请尝试以下步骤：
减少发送的 Token 或请求数量，或降低发送速率。您可能需要降低请求频率或请求量、批量发送 Token，或在响应不包含 Retry-After 时使用指数退避。更多详情，请参阅我们的速率限制指南 。
当响应包含 Retry-After 时，请至少等待其指定的时长后再重试。如果服务器指定的延迟超过 Python 库支持的上限，该库可能会停止自动重试。如果您在应用层重试，请遵守原始延迟要求，并将 SDK 的重试考虑在内。
您也可以在账户控制台中查看 API 使用情况统计信息。
如果问题仍然存在，请通过聊天联系我们的支持团队 ，并提供以下信息：
您使用的模型
您收到的错误消息和错误代码
您发送的请求数据和请求标头
请求的时间戳和时区
其他可能有助于我们诊断问题的相关详情
我们的支持团队将调查此问题，并尽快回复您。请注意，由于咨询量较大，排队等待支持的时间可能较长。您也可以在我们的社区论坛发帖 ，但务必不要包含任何敏感信息。
我们建议您通过程序处理 API 返回的错误。您可以参考以下代码片段来实现：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 import OpenAI from "openai" ;
const client = new OpenAI ();
try {
const response = await client.responses. create ({
model: "gpt-6-astra" ,
input: "Hello world" ,
});
console. log (response.output_text);
} catch (error) {
if (error instanceof OpenAI . APIConnectionError ) {
console. error ( "Failed to connect to the OpenAI API:" , error.message);
} else if (error instanceof OpenAI . RateLimitError ) {
console. error ( "OpenAI API request exceeded its rate limit:" , error.message);
} else if (error instanceof OpenAI . APIError ) {
console. error ( "OpenAI API returned an error:" , error.status, error.message);
} else {
throw error;
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 import openai
from openai import OpenAI
client = OpenAI()
try:
response = client.responses.create(model="gpt-6-astra", input="Hello world")
except openai.APIConnectionError as e:
print(f"Failed to connect to OpenAI API: {e}")
except openai.RateLimitError as e:
print(f"OpenAI API request exceeded rate limit: {e}")
except openai.APIError as e:
print(f"OpenAI API returned an API Error: {e}")
else:
print(response.output_text) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 package main
import (
"context"
"errors"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Hello world")},
})
if err != nil {
var apiError *openai.Error
if errors.As(err, &apiError) {
fmt.Println("OpenAI API returned an API error:", apiError)
return
}
fmt.Println("Failed to connect to OpenAI API:", err)
return
}
fmt.Println(response.OutputText())
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.errors.OpenAIServiceException;
import com.openai.models.responses.ResponseCreateParams;
try {
var response =
client
.responses()
.create(
ResponseCreateParams.builder().model("gpt-6-astra").input("Say hello.").build());
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
} catch (OpenAIServiceException error) {
System.err.println(error.getMessage());
} 1
2
3
4
5
6
7
8
9 require "openai"
client = OpenAI::Client.new
begin
response = client.responses.create(model: "gpt-6-astra", input: "Say hello.")
puts(response.output_text)
rescue OpenAI::Errors::APIError => error
warn(error.message)
end 