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

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Codex常见错误排查：Stream disconnected、400……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

在采用 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 出现以下错误：

Stream disconnected before completion: stream closed before response.completed

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

比如：

https://你的API地址/v1

而不是：

https://你的API地址

从实现思路看，也就是说，需确认接口地址最后是否包含 /v1。

2. 检查 Responses 接口

如果出现：

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

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

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

Windows 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"]}'

其中：

your-api-key

替换成自己的 API Key。

注意：

Bearer

需保留。

Linux / macOS

终端执行：

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

常用报错

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

或者：

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

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

常用原因包括：

1. 模型 ID 填写错误

比如：

gpt5.4
GPT-5.4
gpt-5.4-codex

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

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

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

理解这一步时，若 API Key 对应的渠道策略中，目标模型所有渠道都不可用，也可能得到 503。

这种情况下，需检查：

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

3. 服务端维护

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

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

4. 上游服务异常

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

能够稍后重新发送请求进行测试。

三、401 Unauthorized

常用报错

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

401 基本能够理解为：

身份验证失败。

1. 检查 auth.json

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

比如：

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx"
}

常用问题包括：

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

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

能够根据当前采用方式重新整理认证设置。

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

很多人修改完：

config.toml
auth.json

之后直接继续采用 Codex。

若客户端没有重新读取设置，就可能继续采用旧设置。

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

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

3. 检查 base_url

比如：

错误：

https://你的API地址

正确：

https://你的API地址/v1

实际处理时，若采用的是其他 API 服务，也要确认没有错误地混用了其他服务商的地址。

4. 检查 model_provider

config.toml 中的 model_provider 同样需留意。

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

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

这里的：

model_provider = "OpenAI"

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

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

比如：

model_provider = "OpenAI"

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

需特别注意：

model_provider

对应的是 provider ID。

比如定义的是：

[model_providers.OpenAI]

那么：

model_provider = "OpenAI"

二者需保持一致。

5. API Key 已过期

如果错误信息是：

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

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

理解这一步时，进入 API Key 管理页面，检查 Key 的有效期同时进行调整，然后重新测试。

四、403 Forbidden

常用报错

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

这种情况比较直接：

余额或订阅额度不足。

需进入对应服务的页面检查：

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

API Key 熔断

另外一种常用错误：

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

这种情况通常意味着：

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

落到代码里，能够进入 API Key 管理页面检查当前 Key 状态，同时按照服务端规则恢复熔断。

五、429 Too Many Requests

常用报错

exceeded retry limit, last status: 429 Too Many Requests

429 通常表示：

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

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

比如同时运行大量任务：

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

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

理解这一步时，若服务端按照固定时间窗口统计 Session 同时发量，还需避免在极短时间内一次性新建大量连接。

排查方法

首先减少并发数量。

比如原来同时运行：

10 个 Session

能够先降低到：

2～3 个 Session

然后重新测试。

若降低同时发后恢复正常，基本能够判断是请求频率或并发限制导致。

六、499 Client Closed Request

499 比较特殊。

它通常表示：

客户端主动关闭了请求。

常用情况主要有两种。

1. 用户主动中断

比如 Codex 正在生成：

Task running...

用户点击：

Stop

或者主动关闭 Session。

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

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

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

Waiting...

或者：

Processing...

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

能够尝试：

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

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

七、400 Bad Request

400 表示：

请求参数存在问题。

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

1. 思维等级不兼容

比如：

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

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

比如设置了：

model_reasoning_effort = "xhigh"

但当前模型同时不兼容 xhigh，就可能出现 400。

从实现思路看，解决方法是查看当前模型兼容的 Reasoning Effort，随后修改为对应值。

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

另外一种错误：

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

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

能够尝试：

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

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

八、502 Bad Gateway

常用报错

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

另外也可能出现：

FAKE_200_JSON_ERROR_MESSAGE_NON_EMPTY: stream_read_error

502 一般能够理解为：

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

落到代码里，这种问题很多时候同时不是 Codex 设置错误，而是请求链路中的上游服务出现临时异常。

502 怎么处理？

首先能够直接：

重新发送

如果连续失败，能够：

新建 Session

再进行测试。

若只是偶尔出现一次，一般不需修改设置。

若短时间持续出现，能够进一步检查：

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

九、Codex 常用错误码对照表

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

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

更建议按照下面的顺序排查。

第一步：看 HTTP 状态码

先判断是：

400
401
403
429
499
502
503

还是：

Stream disconnected

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

第二步：检查 base_url

重点确认是否采用类似：

https://你的API地址/v1

不要遗漏：

/v1

第三步：检查 API Key

确认：

OPENAI_API_KEY

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

第四步：检查模型 ID

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

不要自己猜测模型名。

第五步：检查 model_provider

确认：

model_provider

和：

[model_providers.xxx]

采用的是同一个 provider ID。

第六步：降低并发量

如果出现：

429

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

第七步：采用 curl 独立测试

实际处理时，若怀疑是网络问题，能够绕过 Codex 客户端，直接采用 curl 请求：

/v1/responses

这样能够更快判断问题到底来自：

Codex 配置

还是：

网络 / API 服务

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

如果：

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

但仍然出现：

502
503

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

十一、总结

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

轻松来说：

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

而：

Stream disconnected

则需重点检查：

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

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

实际处理时，所以，遇到问题时不要盲目重装 Codex。先看日志、确认错误码，再针对性排查，通常能够更快定位问题。

结合项目来看，本下文的接口地址、模型名称和错误信息属于示例，实际可用的模型、渠道、额度和设置参数应以当前采用的 API 服务为准。