API 没有
先判断失败发生在哪一步：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 检查。 |
| TypeError: Failed to fetch / blocked by CORS policy（浏览器类应用） | 页面代码拿不到可读的 HTTP 状态码：浏览器拦下了响应或它的预检，也可能请求更早就失败了。 | 先在浏览器控制台找「blocked by CORS policy」（同一个 TypeError 也会出现在 DNS、TLS 或离线失败里），再查看 OPTIONS 请求及其 Access-Control-* 响应头；见下文「浏览器应用与 CORS」。 |
| 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 服务器、返回地址或完整解析错误。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 或成功获取模型列表，都不能证明模型生成已经完成。
浏览器
用浏览器 fetch 调用 API 的代码（例如网页，或基于网页技术的桌面应用窗口），在发送带 Authorization 或 x-api-key 请求头和 JSON 请求体的 POST 之前，会先发一次 OPTIONS 预检。自 2026-10-02 起，api.router.one 的 /v1 端点对预检返回 HTTP 204、Access-Control-Allow-Origin: *，并放行浏览器列出的请求头，包括 x-stainless-* 与 anthropic-dangerous-direct-browser-access（2026-10-03 核对）；网关自己返回的错误响应（例如 Key 错误时的 HTTP 401）页面也能读到。浏览器仍报 CORS 错误时，先查主机名和协议：API 主机是 https://api.router.one，发到 router.one 官网主机的预检会收到 HTTP 404 且不带 CORS 响应头；http:// 地址收到的是重定向，而预检请求不能跟随重定向。api.router.one 上路径写错会返回可读的 HTTP 404，不是 CORS 错误。请求在到达网关之前就失败时，错误响应同样不带 CORS 响应头，也会表现为 CORS 错误，这时再查会改写或拦截请求的代理、扩展或客户端设置。
SDK 默认不
按两个 TypeScript SDK 的源码（openai 7.27.0、@anthropic-ai/sdk 0.131.0，2026-10-03 核对），在浏览器中必须显式传 dangerouslyAllowBrowser: true，否则直接报错；Anthropic SDK 打开后还会带上 anthropic-dangerous-direct-browser-access: true。OpenAI SDK 的 baseURL 填 https://api.router.one/v1，Anthropic SDK 填 https://api.router.one。
浏览器
按 Chrome 扩展文档（2026-10-03 核对），拥有 api.router.one 主机权限的扩展 service worker 或扩展页面调用它时，不受网页那样的同源限制；注入网页的 content script 则和所在网页一样受限。
浏览器
写进页面代码的 Key，任何打开页面的人都能读到。面向公众的应用请从你自己的服务端调用 Router One；浏览器直连只适合每个用户填自己 Key 的工具，并给这把 Key 单独设消费上限（maxSpend），在控制台 → 日志里核对它的请求。
收集
确认可到达预期 HTTPS 服务后，再按客户端接入指南发送一次带鉴权的文本请求，并到控制台 → 日志核对结果。若问题持续，可通过联系页面提交这组信息：
- 发生时间与时区、设备系统、应用名称和版本、受影响地区及网络。
- 配置的主机名与 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 命令和证书文档复核；CORS 一节于 2026 年 10 月 3 日依据对 api.router.one 的预检检查、OpenAI 与 Anthropic 两个 TypeScript SDK 的源码以及 Chrome 扩展文档补充。本页命令用于诊断，不是实时可用性报告；连通性检测成功，只验证当时那台设备、网络、主机名与请求。
API 连接
Failed to construct 'URL': Invalid URL 是 API Key 错了吗？
这条消息指向 URL 构造。先检查客户端地址字段是否有格式错误、空 base URL 或重复协议前缀。客户端能够构造预期 URL 并收到 HTTP 响应后，再验证鉴权。
为什么 router.one 能打开，api.router.one 却报 ENOTFOUND？
这是两个不同的主机名，浏览器和 API 客户端也可能使用不同 DNS 或代理设置。先在受影响设备上查询 API 域名，并用无 Key 检测对照应用，再调整账单或模型配置。
控制台 → 日志
不能直接下结论。HTTP 之前失败会出现这种情况，筛选条件、记录延迟或在普通用量记录生成前被拒绝，也可能导致没有记录。保留客户端错误、时间和已有的 request_id，方便支持团队关联证据。
HTTP 200 能证明
它确认收到了 HTTP 响应，不能证明生成完成。本页的模型列表检测没有调用模型；实际生成还要看最终响应或流式终止事件、usage 和对应请求记录。
浏览器报 api.router.one 的 CORS 错误，是 Key 有问题吗？
不是。Key 错误的请求到达网关后，会收到页面可读的 HTTP 401；CORS 错误说明浏览器在页面代码读到任何状态码之前就拦下了这次请求。网关 /v1 端点的预检允许任意来源，并自 2026-10-02 起放行浏览器列出的全部请求头，所以先查主机名和协议（应为 https://api.router.one，而不是 router.one 官网或 http://），再查请求到达网关之前会改写或拦截它的环节。