OpenAI API 错误代码

本页汇总[API](<../01-入门核心概念与开发工具/02-OpenAI API 核心概念.md>)及官方Python SDK可能返回的错误，并给出定位和处理方法。

API错误

账单类错误要看error.code，更宽泛的error.type仍可能为insufficient_quota。账单、支出和配额问题不会因反复重试自动恢复，需先更新额度或限制。

WebSocket模式错误

[Responses WebSocket](<../07-音频语音与实时交互/28-OpenAI Responses WebSocket 模式.md>)还可能返回：previous_response_not_found表示无法解析前一响应，可用完整上下文且previous_response_id设null重启；websocket_connection_limit_reached表示已达60分钟连接上限，应新建连接继续。

400：无效service_tier参数

请求指定或解析出的层级不被项目允许时，返回invalid_request_error，error.param为service_tier。限制适用于default、flex、priority；fast按priority检查。省略或设auto也可能解析到不允许层级；Scale Tier不在此项目策略范围。

检查项目设置和组织层级策略，项目不能开放被组织禁止的层级。改为允许值；auto或省略参数时需使解析结果被项目允许。

401：认证无效

可能使用已撤销密钥、与请求组织/项目不匹配的密钥，或缺少端点权限。核对请求头中的密钥与组织ID，在账户密钥页或选择项目后的设置查看。无法确认时生成新密钥并替换旧值，遵循密钥安全。

401：API密钥不正确

常见原因是拼写/多余空格、密钥属于其他组织或项目、密钥已删/停用，或本地仍缓存已撤销旧值。可清理浏览器缓存与Cookie、核对请求头，必要时重新生成并替换，避免泄露。

401：必须是组织成员

可能已离开或被移出组织/项目，或组织已删除。可联系支持申请组织，或由组织owner在成员页邀请、在设置建项目。项目身份失效则请组织/项目负责人重新加入，或建立新项目。

429：预付余额耗尽

credit_balance_exhausted表示组织预付额度已用完，在账单设置补充额度恢复。

429：请求达到速率上限

短时间词元或请求过多，可能来自高频循环、并发脚本、多人/应用共享密钥、低层级计划或项目限额。减少冗余、调整发送节奏；有Retry-After时至少等指定时间，无头则带抖动指数退避并限制次数。SDK对长等待支持因版本和配置变化，见[重试说明](<OpenAI API 速率限制.md#retrying-with-exponential-backoff>)。

组织额度由团队共同使用，不是每个人各有一份；检查团队用量，按需要升级计划或请组织负责人提高项目限额。

429：请减缓流量

rate_limit_error/slow_down表示增长过快，即使未达到RPM和TPM也可能出现。经验规则：达到100万输入TPM后，每15分钟增长不超过50%；实际触发点依模型及流量条件。

有Retry-After时遵守，无头则增加重试间隔和随机等待；先降流量再逐渐增加，并保持稳定。经常触发的Enterprise按量客户可考虑Scale Tier，5.6及以后见Reserved Tier，但仍需遵守上述恢复规则。

429：组织支出达到上限

organization_spend_limit_exceeded表示组织所有项目共同达到月度[硬上限](<../14-生产部署性能与成本/11-OpenAI 支出限制.md>)。在组织Limits提高/移除，否则等月度重置。

429：项目支出达到上限

project_spend_limit_exceeded仅阻断该项目；其他项目在自身或组织上限未到时可继续。提高/移除项目上限，或等月度重置。

429：组织使用额度达到上限

organization_usage_limit_exceeded是OpenAI批准的[月度使用上限](<OpenAI API 速率限制.md#usage-tiers>)，不同于自设支出上限。申请提高批准额度或联系支持。

503：模型暂时过载

service_unavailable_error/server_is_overloaded表示模型当前容量不足。有Retry-After时至少等待该时间再试，无头则逐步增加间隔；持续发生可查状态页。

Python库错误类型

429对应RateLimitError，503对应InternalServerError。处理器应同时捕获并检查error.code；视频过载等场景从429改为503，见[迁移说明](<OpenAI API 速率限制.md#update-existing-error-handlers>)。

APIConnectionError

请求无法到达服务器或建立安全连接。检查稳定网络，按需换网络/有线或减少带宽竞争；核对代理兼容性；检查证书有效性及更新；核对防火墙规则和容器收发权限。来源排障选项包含更换证书机构或暂时关闭SSL验证；关闭验证会丧失TLS身份校验，不应作为生产常规方案。持续错误按下文收集信息。

APITimeoutError

网络、服务负载或复杂任务使请求过久、连接关闭。可等待数秒重试，检查网络稳定性；持续则按下文处理。

AuthenticationError

密钥/令牌可能无效、过期、撤销，或有拼写、格式、安全事件问题。核对值是否正确且活跃、是否有多余字符；必要时重新生成或改用正确令牌，并遵循认证格式。

BadRequestError

原称InvalidRequestError，表示格式错误或缺少令牌/输入等必需参数。读错误信息中的无效或缺失参数、预期值与格式，核对API参考的名称、类型和大小；检查UTF-8、JSON编码、压缩及请求体尺寸。可用Postman或curl复现，定位应用逻辑问题；持续则联系支持。

InternalServerError

可能是临时故障、缺陷或服务中断。稍后重试，查状态页，有事件时跟进更新并等修复；持续问题提交支持。高需求时支持可能排队，也可在社区讨论，但不披露敏感信息。

RateLimitError

一定时间内请求或词元超限。减少频率、数量及输入量；有Retry-After时遵守，无头才指数退避。Python SDK可能因服务端等待超过支持上限而停止自动重试；应用接手时仍需尊重原等待，并统计SDK已重试次数。用面板核对实际用量。

持续错误

联系支持时提供模型、错误消息/代码、请求数据和头、时间戳/时区及其他诊断细节；先移除密钥和敏感数据。社区公开帖子尤其注意脱敏。支持可能因需求高而等待较久。

处理错误

应以程序处理API错误，来源多语言片段如下；需按实际错误体区分可重试与需配置修复的情况，而非捕获后无条件重试。

来源示例 1（javascript）：

// [中文] 捕获来源SDK的连接、限流或API状态错误；实际恢复前检查HTTP状态和error.code，账单及硬上限不能靠无条件重试解决。示例依赖相应SDK及外围客户端环境。
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;
  }
}

来源示例 2（python）：

## [中文] 捕获来源SDK的连接、限流或API状态错误；实际恢复前检查HTTP状态和error.code，账单及硬上限不能靠无条件重试解决。示例依赖相应SDK及外围客户端环境。
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)

来源示例 3（go）：

// [中文] 捕获来源SDK的连接、限流或API状态错误；实际恢复前检查HTTP状态和error.code，账单及硬上限不能靠无条件重试解决。示例依赖相应SDK及外围客户端环境。
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())
}

来源示例 4（java）：

// [中文] 捕获来源SDK的连接、限流或API状态错误；实际恢复前检查HTTP状态和error.code，账单及硬上限不能靠无条件重试解决。示例依赖相应SDK及外围客户端环境。
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());
}

来源示例 5（ruby）：

## [中文] 捕获来源SDK的连接、限流或API状态错误；实际恢复前检查HTTP状态和error.code，账单及硬上限不能靠无条件重试解决。示例依赖相应SDK及外围客户端环境。
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