LLM API Guide

Codex / Claude Code 接入第三方 API 常见报错排查：401、404、429、超时与断流

LLM API Guide 编辑部（SeedRouter 团队） · 发布 · 更新 · 8 分钟

披露：LLM API Guide 由 SeedRouter 团队维护，文中示例地址为 SeedRouter。排查思路适用于任何 API 网关。

第一步：用 curl 判断问题在哪一侧

curl -i https://seedrouter.net/v1/models \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"
  • 返回 200 和模型列表：Key 和网络都正常，问题在工具配置。
  • 返回 401：Key 有问题。
  • 连接超时或无法解析域名：本地网络、代理或 DNS 的问题。

401 / 403：认证失败

原因处理
Key 复制时带了空格或换行从控制台重新复制
环境变量没加载重开终端，echo $SEEDROUTER_API_KEY 检查是否为空
Key 来自另一个网站Base URL 和 Key 必须来自同一网站，注意名称相近的仿冒站
Key 已停用或余额不足在控制台查看 Key 状态和余额

404：地址或模型不对

  • Codex：base_url 要写到 /v1，例如 https://seedrouter.net/v1，Codex 会拼接 /responses。
  • Claude Code：ANTHROPIC_BASE_URL 只写根地址，例如 https://seedrouter.net，不要带 /v1。
  • 模型不存在：模型 ID 必须与网关模型目录完全一致，包括大小写和连字符。

429：请求过多

  • 同时开了多个 Agent 或并行任务，触发了并发或速率限制。
  • 处理：减少并行数量，稍等后重试；长期需要高并发时联系网关客服确认额度。

超时、524 与流式中断

编程 Agent 的单次请求可能持续好几分钟。请求经过 CDN 或代理时，如果长时间没有任何数据返回，中间层可能主动断开连接，表现为 524、stream disconnected before completion 或输出到一半中断。

排查顺序：

  1. 打开网关状态页（例如 SeedRouter 状态页）看是否有故障。
  2. 检查本地代理或 VPN 是否在切换节点，必要时固定节点再试。
  3. 重试同一任务；如果频繁出现，记录发生时间和请求 ID 发给网关客服。

配置冲突：请求跑到了别处

系统里残留的环境变量会覆盖配置文件：

env | grep -E "OPENAI|ANTHROPIC"

常见的冲突变量有 OPENAI_BASE_URL、OPENAI_API_KEY、ANTHROPIC_API_KEY。确认不需要后从 ~/.zshrc、~/.bashrc 或系统环境变量中删除，再重开终端。Windows 可以在 PowerShell 里用 Get-ChildItem Env: 查看。

联系客服前准备好这些信息

  • 使用的工具和版本（codex --version、claude --version）
  • 报错原文截图、发生时间
  • 模型 ID、Base URL（不要发送完整 API Key）

SeedRouter 用户可以发邮件到 support@seedrouter.net，一个工作日内回复。配置方法见 Codex CLI 接入第三方 API 和 Claude Code 使用第三方 API。

常见问题

怎么判断是本地配置问题还是网关故障？

用 curl 直接请求网关的 /v1/models。curl 也失败多半是 Key 或地址问题；curl 正常而工具报错，多半是工具配置或环境变量冲突；多人同时报错时先看网关状态页。

Codex 报 stream disconnected before completion 怎么办？

先重试一次，再检查本地代理、VPN 是否切换节点，并查看网关状态页。长时间推理的请求需要网关持续发送数据，选择对长流式请求做过优化的网关能减少这类中断。

改了配置一直不生效？

Codex 和 Claude Code 都在启动时读取配置。退出工具、关闭终端窗口后重新打开，再启动一次。