Codex 常见错误排查指南：Stream disconnected、400、401、403、429、502、503 解决方法

大家好，这里是「代码简单说」。

在使用 Codex 的过程中，无论是 Visual Studio Code 中的 Codex 插件、Codex CLI，还是 Codex App，都可能遇到各种网络、API Key、模型配置以及上游服务异常。

很多报错看起来比较复杂，但实际上通过错误码和日志信息，通常可以快速定位问题。

本文整理一套比较常见的 Codex 错误排查方法，包括：

Stream disconnected 连接错误
400 Bad Request
401 Unauthorized
403 Forbidden
429 Too Many Requests
499 Client Closed Request
502 Bad Gateway
503 Service Unavailable

本文中的 Codex 应用 泛指 Codex App、Codex CLI、IDE 插件等使用 Codex 的客户端。其他兼容应用也可以参考相同的排查思路。

一、Stream disconnected 连接错误

1. 常见报错

如果 Codex 出现以下错误：

text 复制代码

Stream disconnected before completion: stream closed before response.completed

优先检查 base_url 配置是否正确。

例如：

text 复制代码

https://你的API地址/v1

而不是：

text 复制代码

https://你的API地址

也就是说，需要确认接口地址最后是否包含 /v1。

2. 检查 Responses 接口

如果出现：

text 复制代码

Stream disconnected before completion: error sending request for url (https://你的API地址/v1/responses)

通常需要优先检查本地网络环境。

可以使用 curl 直接测试接口是否能够正常建立连接。

Windows PowerShell

打开 PowerShell，执行：

powershell 复制代码

curl.exe https://你的API地址/v1/responses `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer your-api-key" `
  -d '{\"model\":\"gpt-5.4-mini\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"你好\"}]}],\"store\":false,\"stream\":true,\"include\":[\"reasoning.encrypted_content\"]}'

其中：

text 复制代码

your-api-key

替换成自己的 API Key。

注意：

text 复制代码

Bearer

需要保留。

Linux / macOS

终端执行：

bash 复制代码

curl https://你的API地址/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
  "model": "gpt-5.4-mini",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "你好"
        }
      ]
    }
  ],
  "store": false,
  "stream": true,
  "include": [
    "reasoning.encrypted_content"
  ]
}'

如果 curl 本身就无法正常返回结果，优先排查网络连接、DNS、请求链路和出口节点。

也可以尝试更换网络环境，检查是否存在代理、网络拦截或者连接不稳定的问题。

二、503 Service Unavailable

常见报错

text 复制代码

Unexpected status 503 Service Unavailable: 所有渠道不可提供当前模型，请稍后重试

或者：

text 复制代码

Unexpected status 503 Service Unavailable: 服务暂时不可用，请稍后重试

503 通常表示服务器当前无法处理请求。

常见原因包括：

1. 模型 ID 填写错误

例如：

text 复制代码

gpt5.4
GPT-5.4
gpt-5.4-codex

模型名称必须以当前服务实际支持的模型 ID 为准。

不要仅凭模型名称猜测 API 模型。

2. 渠道策略没有可用渠道

如果 API Key 对应的渠道策略中，目标模型所有渠道都不可用，也可能返回 503。

这种情况下，需要检查：

当前模型是否支持
当前渠道是否可用
渠道策略是否正确
是否存在临时故障

3. 服务端维护

如果服务正在维护，也可能直接出现 503。

这种情况一般不需要修改 Codex 配置，等待服务恢复即可。

4. 上游服务异常

如果 API 服务本身正常，但上游服务出现异常，同样可能出现 503。

可以稍后重新发送请求进行测试。

三、401 Unauthorized

常见报错

text 复制代码

Unexpected status 401 Unauthorized: API Key 无效，请检查后重试

401 基本可以理解为：

身份验证失败。

1. 检查 auth.json

如果已经正确配置 base_url，需要重点检查 auth.json。

例如：

json 复制代码

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx"
}

常见问题包括：

API Key 填写错误
缺少 sk- 前缀
Key 已失效
Key 复制时多了空格
auth.json 中混入了其他不必要字段

特别是之前曾经在 Codex 应用中登录过官方账号的情况下，auth.json 可能包含额外登录信息。

可以根据当前使用方式重新整理认证配置。

2. 修改配置后重新启动 Codex

很多人修改完：

text 复制代码

config.toml
auth.json

之后直接继续使用 Codex。

如果客户端没有重新读取配置，就可能继续使用旧配置。

因此修改认证信息后，建议：

完全退出 Codex 应用，再重新启动。

3. 检查 base_url

例如：

错误：

text 复制代码

https://你的API地址

正确：

text 复制代码

https://你的API地址/v1

如果使用的是其他 API 服务，也要确认没有错误地混用了其他服务商的地址。

4. 检查 model_provider

config.toml 中的 model_provider 同样需要注意。

下面这种写法就是错误示范：

toml 复制代码

[sandbox_workspace_write]
network_access = true
model_provider = "OpenAI"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"

这里的：

toml 复制代码

model_provider = "OpenAI"

被放到了错误的配置区块中。

正确配置应该根据 provider 定义进行对应。

例如：

toml 复制代码

model_provider = "OpenAI"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://你的API地址/v1"
wire_api = "responses"
requires_openai_auth = true

需要特别注意：

toml 复制代码

model_provider

对应的是 provider ID。

例如定义的是：

toml 复制代码

[model_providers.OpenAI]

那么：

toml 复制代码

model_provider = "OpenAI"

二者需要保持一致。

5. API Key 已过期

如果错误信息是：

text 复制代码

Unexpected status 401 Unauthorized: API Key 已过期，请前往API Key管理修改到期时间后重试

那么就不是 Codex 本身的问题。

进入 API Key 管理页面，检查 Key 的有效期并进行调整，然后重新测试。

四、403 Forbidden

常见报错

text 复制代码

Unexpected status 403 Forbidden: 余额和订阅额度均不足，请充值后再使用

这种情况比较直接：

余额或订阅额度不足。

需要进入对应服务的账户管理页面检查：

账户余额
套餐额度
模型额度
API Key 使用额度

API Key 熔断

另外一种常见错误：

text 复制代码

Unexpected status 403 Forbidden: API Key 熔断已开启，请稍后重试

这种情况通常意味着：

该 API Key 在短时间内连续请求失败，触发了熔断机制。

可以进入 API Key 管理页面检查当前 Key 状态，并按照服务端规则恢复熔断。

五、429 Too Many Requests

常见报错

text 复制代码

exceeded retry limit, last status: 429 Too Many Requests

429 通常表示：

请求频率或并发数量超过限制。

使用 Codex 时，特别容易出现在多个 Agent、多个 Session 同时运行的情况下。

例如同时运行大量任务：

text 复制代码

Codex Session 1
Codex Session 2
Codex Session 3
Codex Session 4
...

短时间内产生大量请求后，就可能触发限制。

如果服务端按照固定时间窗口统计 Session 并发量，还需要避免在极短时间内一次性创建大量连接。

排查方法

首先减少并发数量。

例如原来同时运行：

text 复制代码

10 个 Session

可以先降低到：

text 复制代码

2～3 个 Session

然后重新测试。

如果降低并发后恢复正常，基本可以判断是请求频率或并发限制导致。

六、499 Client Closed Request

499 比较特殊。

它通常表示：

客户端主动关闭了请求。

常见情况主要有两种。

1. 用户主动中断

例如 Codex 正在生成：

text 复制代码

Task running...

用户点击：

text 复制代码

Stop

或者主动关闭 Session。

这种情况下看到 499 不需要过度担心。

2. 客户端等待超时后主动断开

如果没有人为停止，但 499 经常出现，同时 Codex 长时间卡在：

text 复制代码

Waiting...

或者：

text 复制代码

Processing...

就需要进一步排查请求链路和服务响应时间。

可以尝试：

中断当前任务
重新发送继续指令
新建一个 Session
检查当前网络连接
观察是否持续出现 499

如果只有偶尔一次，一般无需特殊处理。

七、400 Bad Request

400 表示：

请求参数存在问题。

与 401 不同，400 通常不是 Key 本身失效，而是请求内容或参数不符合接口要求。

1. 思维等级不支持

例如：

json 复制代码

{
  "error": {
    "message": "设定的思维等级不被支持，请修改后重试",
    "type": "invalid_request_error",
    "code": "bad_request"
  }
}

这说明当前模型不支持你设置的思维等级。

例如配置了：

toml 复制代码

model_reasoning_effort = "xhigh"

但当前模型并不支持 xhigh，就可能出现 400。

解决方法是查看当前模型支持的 Reasoning Effort，然后修改为对应值。

2. 请求包含不允许的内容

另外一种错误：

json 复制代码

{
  "error": {
    "message": "请求包含不允许的内容，请修改后重试",
    "type": "invalid_request_error",
    "code": "bad_request"
  }
}

这类问题通常与请求内容或服务端安全策略有关。

可以尝试：

修改当前输入内容
删除容易触发安全策略的指令
换一个测试 Prompt
切换其他可用渠道

不要仅仅反复重试完全相同的请求。

八、502 Bad Gateway

常见报错

text 复制代码

An error occurred while processing your request. You can retry your request, or contact us through our help center if the error persists. Please include the request ID 3dec60df-2c8

另外也可能出现：

text 复制代码

FAKE_200_JSON_ERROR_MESSAGE_NON_EMPTY: stream_read_error

502 一般可以理解为：

网关无法正常从上游获得有效响应。

这种问题很多时候并不是 Codex 配置错误，而是请求链路中的上游服务出现临时异常。

502 怎么处理？

首先可以直接：

text 复制代码

重新发送

如果连续失败，可以：

text 复制代码

新建 Session

再进行测试。

如果只是偶尔出现一次，一般不需要修改配置。

如果短时间持续出现，可以进一步检查：

当前模型
当前渠道
当前网络
API 服务状态
上游服务状态

九、Codex 常见错误码对照表

错误	常见含义	优先检查
Stream disconnected	流式连接中断	`base_url`、网络、请求链路
400	请求参数错误	模型参数、思维等级、请求内容
401	身份认证失败	API Key、`auth.json`、provider
403	权限 / 额度 / 熔断	余额、额度、Key 状态
429	请求过于频繁	Session 并发、RPM
499	客户端关闭请求	手动中断、超时
502	网关或上游异常	重试、Session、上游状态
503	服务暂时不可用	模型、渠道、服务器状态

十、建议按照这个顺序排查

当 Codex 出现未知错误时，不要一看到错误码就直接修改大量配置。

更推荐按照下面的顺序排查。

第一步：看 HTTP 状态码

先判断是：

text 复制代码

还是：

text 复制代码

Stream disconnected

不同错误对应的问题完全不同。

第二步：检查 base_url

重点确认是否采用类似：

text 复制代码

https://你的API地址/v1

不要遗漏：

text 复制代码

/v1

第三步：检查 API Key

确认：

text 复制代码

OPENAI_API_KEY

是否正确，是否过期，以及 auth.json 是否存在错误配置。

第四步：检查模型 ID

确认当前模型名称是否真实存在，并且当前服务支持。

不要自己猜测模型名。

第五步：检查 model_provider

确认：

toml 复制代码

model_provider

和：

toml 复制代码

[model_providers.xxx]

使用的是同一个 provider ID。

第六步：降低并发量

如果出现：

text 复制代码

优先降低 Session 并发数量，而不是不停重试。

第七步：使用 curl 独立测试

如果怀疑是网络问题，可以绕过 Codex 客户端，直接使用 curl 请求：

text 复制代码

/v1/responses

这样可以快速判断问题到底来自：

text 复制代码

Codex 配置

还是：

text 复制代码

网络 / API 服务

第八步：最后再考虑服务端问题

如果：

API Key 正确
base_url 正确
模型正确
provider 正确
curl 正常
Codex 配置也正常

但仍然出现：

text 复制代码

502
503

那么就应该重点考虑服务端或上游服务临时异常。

十一、总结

Codex 报错并不可怕，关键是先根据错误类型定位问题。

简单来说：

text 复制代码

400 → 请求参数
401 → API Key
403 → 权限 / 额度 / 熔断
429 → 请求频率 / 并发
499 → 客户端关闭连接
502 → 网关 / 上游异常
503 → 服务暂时不可用

而：

text 复制代码

Stream disconnected

则需要重点检查：

text 复制代码

base_url
网络连接
流式响应
/v1/responses

尤其是使用自定义 API 服务时，很多问题并不是 Codex 本身出现故障，而是 API Key、provider、模型、接口地址以及网络链路之间的某一环配置不正确。

因此，遇到问题时不要盲目重装 Codex。先看日志、确认错误码，再针对性排查，通常可以更快定位问题。

本文中的接口地址、模型名称和错误信息属于示例，实际可用的模型、渠道、额度和配置参数应以当前使用的 API 服务为准。