Codex/Claude Code 报 401、404、429、502 或超时:用一条 /models 命令定位故障

透明说明:本文由 AI 辅助整理,命令、事实与发布内容仍需作者复核。

Codex、Claude Code 或 OpenAI 兼容客户端突然不可用,并不等于客户端需要重装。面对 401、404、429、502 或连接超时,可以先请求 Base URL 下的 /models,把问题归到鉴权、接口路径、限流、上游异常或本地网络。准备好 Node.js 20 及以上环境后,第一条诊断命令是:

node llm-api-doctor.mjs --base-url https://api.example.com/v1

命令默认从 LLM_API_KEY 环境变量读取密钥。输出中的 classification 是首要判断结果,statusCode、retryAfterSeconds 和 nextActions 用于复核原因和决定下一步。正常情况下,三分钟内即可取得首个分类结果;它只负责定位,不承诺修复服务端故障。

为什么先查 /models

同一个“客户端连不上”现象可能来自完全不同的环节。密钥不匹配会返回 401;Base URL 漏写 /v1 或服务没有对应接口时可能返回 404;并发或额度限制可能表现为 429;网关或上游异常可能返回 502;DNS、代理、证书、端口和请求时间过长则可能表现为连接错误或超时。

诊断工具会删除 Base URL 末尾多余的斜杠,再拼接 /models。例如输入:

https://api.example.com/v1

实际探测地址为:

https://api.example.com/v1/models

请求方法是 GET,带鉴权时使用 Authorization: [REDACTED] ...。工具不会发送提示词、代码或其他对话内容,也不会修改 Codex、Claude Code 或网关配置。因此,这一步适合放在重装客户端、改代理或反复更换模型名之前。

先完成一次真实接口探测

资源目录应至少包含 llm-api-doctor.mjs。先确认运行环境:

node --version

Node.js 需不低于 20。随后把密钥写入环境变量,不要使用工具的命令行参数传递密钥:

export LLM_API_KEY="替换为实际密钥"
node llm-api-doctor.mjs \
  --base-url https://api.example.com/v1

如果客户端使用的是另一个环境变量,例如 OPENAI_API_KEY,显式指定变量名:

node llm-api-doctor.mjs \
  --base-url https://api.example.com/v1 \
  --key-env OPENAI_API_KEY

本地无需鉴权的兼容服务可以执行:

node llm-api-doctor.mjs \
  --base-url http://127.0.0.1:11434/v1 \
  --no-auth

不要把密钥放进 Base URL。带用户名、密码、查询参数或片段的地址会被判定为 invalid_base_url。环境变量不存在时,结果是 missing_api_key,此时请求尚未发送,先修正本地配置即可。

怎样读懂结构化结果

成功访问 /models 时,核心字段类似:

{
  "ok": true,
  "classification": "ok",
  "statusCode": 200,
  "retryAfterSeconds": null,
  "nextActions": [
    "接口可访问;再核对调用工具使用的模型名和请求格式。"
  ]
}

ok 只说明模型列表接口可访问,不能证明某个具体模型已有调用权限。若诊断失败,按下面的顺序处理:

  • authentication_failed:对应 401。核对密钥所属平台、Base URL 以及服务要求的鉴权方式。更换客户端安装目录不能修正错误密钥。
  • permission_denied:对应 403。检查账号权限、模型权限、地区策略或网关访问控制。
  • endpoint_not_found:对应 404。优先确认 Base URL 是否漏写 /v1,再查服务文档是否实现 /models。
  • rate_limited:对应 429。查看 retryAfterSeconds;服务返回 Retry-After 时,工具会把整数秒或日期转换为等待秒数。等待后再试,并检查额度与并发。
  • upstream_error:覆盖 500 及以上 HTTP 状态,因此 502 会进入此类。保留状态码、发生时间和探测地址,稍后重试并查看服务状态。
  • request_timeout:请求在设定时间内没有完成。先区分 /models 的网络超时与客户端生成长内容时的模型超时,再检查代理和上游。
  • dns_failed、connection_refused、tls_failed:分别检查域名与 DNS、本地服务和端口、系统时间与证书链。TLS 失败时不应通过关闭证书校验规避问题。

若收到未单独分类的其他 HTTP 状态,结果为 http_error;其他网络异常会归入 network_error。这些分类是继续排查的入口,不是对服务商内部根因的证明。

如何复现附件中的离线测试

附件包含 test/run-tests.mjs,执行:

node test/run-tests.mjs

证据包记录的实际输出为:

llm-api-doctor tests passed

测试会启动仅监听 127.0.0.1 随机端口的临时 HTTP 服务,不访问真实模型接口。它实际覆盖了 200 成功、401 鉴权失败、404 接口不存在、429 限流、500 上游异常、100 毫秒超时、密钥缺失、非法 URL 和连接拒绝;还断言 429 返回的 Retry-After: 12 被解析为 12 秒,并检查测试密钥没有出现在结构化结果中。

需要注意,本地用例直接模拟的是 500,而不是 502。源码将所有大于等于 500 的状态统一映射为 upstream_error,所以 502 的分类可以从代码逻辑确认,但不能表述为已经连接真实 502 服务完成验证。离线测试也不构成生产网络、代理、证书或实际账号权限验证。

没得到预期结果时查什么

命令直接提示 --base-url is required,说明参数缺失;提示未知参数时,应删除资源未支持的选项。--key-env 只接受大写字母、数字和下划线组成且以大写字母或下划线开头的环境变量名。

结果为 invalid_base_url 时,使用完整的 http:// 或 https:// 地址,并移除查询参数、片段和嵌入式凭据。结果为 missing_api_key 时,检查当前终端是否确实继承了指定环境变量。

如果接口文档明确说明不提供 /models,404 不能直接证明 Base URL 错误,只能说明本次探测地址不存在。此时应以平台文档为准。若诊断为 ok,客户端仍然报错,则继续核对模型名、请求格式和客户端自身日志;不要把模型列表成功解释成生成接口一定可用。

这套方法适合什么情况

适用场景是 Codex、Claude Code、OpenAI 兼容网关或本地模型接口配置后的第一轮连接排查,以及把统一的分类、状态码和等待时间交给运维人员或服务商继续定位。它尤其适合处理“表面都是连接失败,但无法判断该查密钥、地址还是网络”的故障。

不适合用它验证流式输出、模型质量、具体模型权限、长任务超时、额度余额、账单状态或服务商内部健康情况。工具不会发送生成请求,也不能代替平台状态页。实际网络中 DNS、TLS 和代理分类尚未由证据包里的离线测试完成生产验证,结论应结合当前网络环境复核。

资源

  • 资源名称:大模型 API 401、404、429、5xx 与超时连接诊断工具
  • 下载地址:https://download.csdn.net/download/zyx022/93227414
  • 说明:这是本文配套资源,包含无第三方依赖的诊断脚本、使用说明、本地离线测试和许可证文件。
Logo

汇聚全球AI编程工具,助力开发者即刻编程。

更多推荐