API 没有返回 HTTP，连接错误怎么排查？
先判断失败发生在哪一步：URL 构造 → 域名解析 → 连接与 TLS → HTTP 响应 → 模型结果。Invalid URL、ENOTFOUND、证书错误与已经返回的 401、429，排查方法不同。在出问题的设备和网络上，用小范围只读检测对照客户端表现，保留完整错误后再调整配置。
先定位失败层级
请求日志里没有记录只是线索，不能单独证明原因。客户端可能尚未到达网关，也可能是请求提前被拒绝、日志筛选或记录延迟。先看客户端实际收到了什么。
| 看到的信号 | 说明了什么 | 下一步 |
|---|---|---|
| Invalid URL / ERR_INVALID_URL | 客户端没能构造出可用的 URL。 | 检查 API Host 或 Base URL 原始值，以及客户端如何拼接路径。 |
| ENOTFOUND / EAI_AGAIN | 域名查找失败；EAI_AGAIN 表示临时查找失败。 | 核对具体主机名、解析结果及应用实际使用的网络环境。 |
| 连接被拒绝、重置或超时 | 连接被拒绝、中断或超时，需要继续区分发生阶段。 | 对照应用与 curl，检查代理、防火墙和是否已经收到 HTTP 响应。 |
| 证书校验或主机名错误 | TLS 对端验证未成功。 | 检查系统时间、主机名、证书信任及受管理网络中的 HTTPS 检查。 |
| HTTP 401 / 403 / 429 / 5xx | 某个 HTTP 服务返回了状态码。 | 结合响应头和正文辨认返回服务，再按 API 错误码指南处理。 |
Invalid URL：先修正地址，再核对路径
API Host 或 Base URL 中只填写地址本身。检查是否粘贴了 Markdown 链接、外层引号或方括号、重复的 https://，以及意外空白。空或无效的 base URL 会让 JavaScript URL 构造器在发出网络请求前抛错；语法有效的 URL 也仍可能指向错误的 API 路径。
| 对应接入指南中的配置 | 应填写的值 |
|---|---|
| OpenAI SDK base_url / baseURL；Codex base_url | https://api.router.one/v1 |
| Claude Code ANTHROPIC_BASE_URL | https://api.router.one |
| NextChat BASE_URL | https://api.router.one |
| 沉浸式翻译自定义接口；Copilot 使用 Chat Completions 时的 models[].url | https://api.router.one/v1/chat/completions |
- 以上值对应链接指南中的具体配置。其他 provider、客户端版本或 API 类型可能使用不同字段。
- API Key 填在专用密钥字段，不要放进 URL。
- 若客户端只在启动时读取配置，修正后重新加载或重启。再次增删 /v1 前，先确认实际请求路径。
在出问题的设备上检查 DNS
在与应用相同的设备和网络运行下列只读查询，记录 DNS 服务器、返回地址或完整解析错误。router.one 与 api.router.one 是两个主机名，能打开网站不能证明 API 域名也能解析。
nslookup api.router.one nslookup router.one
- 与另一网络或允许使用的其他解析器对照。不同结果本身不能证明网络干预，缓存和路由差异也可能造成不同答案。
- nslookup 成功不代表应用走同一条解析路径。还需检查本地 hosts 覆盖、应用代理、VPN/TUN 状态及运行时解析器；Node.js 的 dns.lookup 使用操作系统的名称查找机制。
- 仅凭 ENOTFOUND 不能认定域名过期或服务下线。EAI_AGAIN 提示临时查找失败，可以短暂重试；持续发生时再调查原因。
不带 API Key 检测 HTTPS
以下 macOS/Linux 命令只向模型列表路径发送只读 GET，不携带 API Key，也不请求生成。-q 跳过 curl 默认配置文件，证书校验保持开启，也不自动跟随重定向。默认丢弃响应正文，先看状态码、Content-Type 与 Location 响应头；若仍无法确认来源，去掉 --output /dev/null 后检查正文。Windows PowerShell 请使用 curl.exe，将命令合为一行，并把 /dev/null 改为 NUL。
curl -q --silent --show-error --connect-timeout 10 --max-time 20 \
--dump-header - --output /dev/null \
--write-out 'http_code=%{http_code} remote_ip=%{remote_ip}\n' \
https://api.router.one/v1/models| 结果 | 如何解读 |
|---|---|
| curl: (5) / (6) | curl 无法解析代理或目标主机，先检查错误里点名的主机名。 |
| curl: (7) / (28) | 连接失败或超时，保留完整消息以判断发生阶段。 |
| curl: (35) / (60) | TLS 连接或证书校验失败，按下方 TLS 检查处理。 |
| http_code=000 | curl 没有取得 HTTP 响应码。000 是诊断输出，不是 API 返回的状态码。 |
| HTTP 401 或其他状态码 | 已经到达某个 HTTP 服务。不带 Key 的检测可能收到网关鉴权拒绝；仍需结合响应头与正文确认来源。 |
| HTTP 重定向或异常 HTML 页面 | 记录 Location 响应头与页面类型，核对域名、网络和代理路径后再发送凭证。 |
区分 TLS、代理与应用自身差异
证书失败时，先核对设备时间和配置的主机名，再按应用或运行时支持的方式更新证书信任库。受管理网络可请 IT 核对 HTTPS 检查证书及信任配置。证书错误说明验证失败，不能仅凭它判断责任方。
curl 能通，应用仍失败
对照应用保存的 URL、代理选择、运行时版本及证书信任库。桌面应用和终端可能继承不同设置，先在同一网络复现，再判断是否属于上游故障。
只有一个网络失败
记录两边的地区、运营商或企业网络、时间、DNS 答案及失败层级。这能缩小排查范围，但不能单独认定责任方；curl 输出的 remote_ip 也可能是代理或边缘节点地址。
收到 HTTP 后才断开
此时已经越过最初的连接阶段。保留已接收内容和 request_id，转到流式指南检查终止事件。HTTP 200 或成功获取模型列表，都不能证明模型生成已经完成。
收集支持团队可用的证据
确认可到达预期 HTTPS 服务后，再按客户端接入指南发送一次带鉴权的文本请求，并到 Dashboard → Logs 核对结果。若问题持续，可通过联系页面提交这组信息：
- 发生时间与时区、设备系统、应用名称和版本、受影响地区及网络。
- 配置的主机名与 API 路径、所选协议及精确模型 ID；移除其中的凭证或私密查询参数。
- 完整错误 code 和 message；如有，附 HTTP 状态、响应类型及 request_id。HTTP 之前失败可能没有 request_id。
- DNS 查询与无 Key curl 检测结果；另一网络或另一客户端是否表现不同。
- 不要附 API Key、Authorization 请求头、Cookie、代理密码或私人 prompt；截图和日志分享前先脱敏。
适用范围与来源
2026 年 9 月 9 日依据下方链接的 URL 标准、Node.js 与 libuv 错误文档、curl 命令和证书文档复核。本页命令用于诊断，不是实时可用性报告；连通性检测成功，只验证当时那台设备、网络、主机名与请求。
API 连接排查常见问题
Failed to construct 'URL': Invalid URL 是 API Key 错了吗？
这条消息指向 URL 构造。先检查客户端地址字段是否有格式错误、空 base URL 或重复协议前缀。客户端能够构造预期 URL 并收到 HTTP 响应后，再验证鉴权。
为什么 router.one 能打开，api.router.one 却报 ENOTFOUND？
这是两个不同的主机名，浏览器和 API 客户端也可能使用不同 DNS 或代理设置。先在受影响设备上查询 API 域名，并用无 Key 检测对照应用，再调整账单或模型配置。
Dashboard → Logs 没有记录，就说明请求没到网关吗？
不能直接下结论。HTTP 之前失败会出现这种情况，筛选条件、记录延迟或在普通用量记录生成前被拒绝，也可能导致没有记录。保留客户端错误、时间和已有的 request_id，方便支持团队关联证据。
HTTP 200 能证明模型调用成功吗？
它确认收到了 HTTP 响应，不能证明生成完成。本页的模型列表检测没有调用模型；实际生成还要看最终响应或流式终止事件、usage 和对应请求记录。