Codex 常见错误码对照表

Codex 接入或在命令行里跑代码生成、补全、任务执行时，最常见的不是“模型不工作”，而是请求在鉴权、模型名、额度、网络或参数校验这几步被拦住。排查时不要先改业务代码，建议先看三件事：HTTP 状态码、返回体里的 error.type / error.code、本地环境变量是否真的生效。

一、常见错误码对照

状态码 / 错误	常见现象	优先排查点
400 Bad Request	请求直接失败，提示参数非法、消息格式不对	模型名、JSON 结构、字段类型、上下文长度
401 Unauthorized	提示 API key 无效或未提供	环境变量、Header、Key 是否复制完整
403 Forbidden	有 Key 但无权限访问某模型或资源	账号权限、模型权限、组织配置
404 Not Found	提示 model not found 或接口路径不存在	模型名称、Base URL、接口版本
408 / timeout	请求等待很久后超时	网络、代理、请求超时时间、输入过大
429 Rate Limit	短时间内多次请求后被限流	并发数、重试策略、额度和 RPM/TPM 限制
500	服务端内部错误，偶发较多	重试、缩小请求、观察是否持续复现
502 / 503 / 504	网关错误、服务不可用、网关超时	网络链路、中转服务、服务端繁忙
ENOTFOUND	本地报 DNS 解析失败	域名、DNS、代理、公司网络限制
ECONNRESET	连接被重置，请求中途断开	代理稳定性、网络质量、请求体大小

二、错误现象怎么判断

先把错误原文打印出来，不要只看封装后的“请求失败”。很多 SDK 会把响应体包在异常对象里，真正有用的信息在 response.data 或 error.message。

### token云桥中转 0029.org ###
curl -i \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "codex-mini-latest",
    "input": "Write a Python function to reverse a string."
  }' \
  "$OPENAI_BASE_URL/v1/responses"

这里建议加上 -i，能同时看到响应头和状态码。只看终端最后一行，很容易把 401 当成网络问题，把 404 当成模型不可用。

三、按顺序排查原因

1. 先查 Key 和环境变量

401 基本优先怀疑 Key。尤其是在 VS Code、Cursor、Docker、CI 里，环境变量经常不是你以为的那个值。

echo "$OPENAI_API_KEY" | sed 's/.\{8\}$/********/'

如果在 Docker 里跑，需要进容器确认：

docker exec -it my-codex-app sh
printenv | grep OPENAI

注意不要把 Key 写进代码仓库。临时测试可以用命令行导出，长期使用建议放到 CI Secret 或服务器环境变量里。

2. 再查 Base URL 和模型名

404 最容易出现在 Base URL 拼错、接口路径写错、模型名写成旧名字这几种情况。比如有些 SDK 默认走官方地址，你以为配置了中转地址，实际没有生效。

echo "$OPENAI_BASE_URL"

如果国内网络不稳定，或者团队里多人共用额度和模型配置，我一般会建议把中转层固定下来再排错，减少变量。比如 token 云桥 AI 中转站 0029.org，适合先做连通性验证和团队统一入口；但仍然要确认它提供的 Base URL、模型名和你代码里保持一致。

3. 检查请求体格式

400 多半是请求结构问题。常见坑包括：把数组写成字符串、字段名拼错、温度值传了字符串、输入内容超过上下文限制。

{
  "model": "codex-mini-latest",
  "input": [
    {
      "role": "user",
      "content": "Generate a unit test for this function."
    }
  ]
}

如果不确定是不是上下文太长，可以先把输入缩短到几十个字。短请求能成功，长请求失败，就优先查 token 长度、文件拼接逻辑、日志是否把大段内容一起传进去了。

4. 处理限流和超时

429 不要用死循环硬重试，越重试越容易雪崩。建议加指数退避，并限制并发。

for i in 1 2 3 4; do
  echo "try $i"
  curl -s -o /tmp/codex.out -w "%{http_code}\n" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"codex-mini-latest","input":"Say ok"}' \
    "$OPENAI_BASE_URL/v1/responses"
  sleep $((i * 2))
done

如果是 408、504，先用最小请求验证链路，再逐步恢复真实输入。很多时候不是模型慢，而是代理或网关的超时时间比模型返回时间短。

四、修复后的验证方式

修好后不要只跑一次业务流程，建议做三层验证：

• 最小请求：确认 Key、Base URL、模型名可用。
• 真实短请求：确认业务 SDK 的参数格式没问题。
• 真实长请求：确认上下文长度、超时和重试策略能扛住。

curl -s \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"codex-mini-latest","input":"Return only the word pong."}' \
  "$OPENAI_BASE_URL/v1/responses"

如果返回内容稳定，并且日志里没有 401、429、5xx，再切回完整业务流程。线上服务最好把状态码、请求耗时、重试次数记录下来，后续排查会省很多时间。

五、避免复发的几个习惯

• 模型名和 Base URL 不要散落在多个文件里，统一放配置中心或环境变量。
• 所有请求加超时，不要使用无限等待。
• 对 429 和 5xx 做有限次数重试，对 400、401 不要盲目重试。
• 上线前用最小请求做健康检查，避免部署后才发现 Key 没注入。
• 日志里记录错误码和错误类型，但不要打印完整 API Key 和敏感输入。

总结

Codex 报错先按状态码分层处理：401 查 Key，404 查地址和模型名，400 查请求体，429 查限流，5xx 查重试和链路稳定性。排错时用最小 curl 请求切开问题边界，比直接改业务代码更快。