404 不一定表示网站不存在。在 AI API 场景里，它通常代表两类问题：请求发到了错误路径，或者你填写的模型名称不存在。部分客户端还会把分组权限不足包装成 model_not_found，所以排查时要把地址、模型名和 Key 权限放在一起看。
好消息是，404 和 401 一样属于「机械可穷举」的报错：原因清单就那么几条，逐项核对必有结论，不需要碰运气式地重装和重试。这篇给出完整的判断方法和检查顺序，最后用一个最小请求收尾验证。
先看错误正文，分清是哪种 404
不要只看客户端弹窗标题。找到原始状态码和错误正文里的关键词，能少走大量弯路：
| 错误特征 | 更可能的原因 |
|---|---|
| 页面式 404、找不到路由 | API 地址拼错 |
model_not_found | 模型名称错误或不可用 |
not_found_error | Claude 协议的路径或模型配置错误 |
| 客户端只显示「请求失败」 | 需要翻客户端日志找真实响应 |
大多数客户端都有日志或调试面板，里面记录着完整的请求 URL 和响应正文——这两样东西是 404 排查的全部原材料。
为什么客户端总把真实错误藏起来？因为面向普通用户的产品倾向于展示「友好」的提示，把服务端返回的状态码和错误字段包装成一句「请求失败，请稍后重试」。这对普通用户是善意，对排查问题的你是障碍。所以排查的第一原则永远是：绕过包装，拿到原始响应。 翻日志、开调试模式，或者干脆用 curl 在终端里复现。
现象 → 原因 → 解法 对照表
| 现象 | 原因 | 解法 |
|---|---|---|
| 所有请求都 404 | Base URL 缺 /v1 或多拼了路径 | OpenAI 工具填 https://zivv.pro/v1 |
| Claude Code 全部 404 | ANTHROPIC_BASE_URL 误加了 /v1 | 只填 https://zivv.pro |
报 model_not_found | 模型名拼错、带空格或版本已下线 | 从当前模型列表复制准确 id |
| 能调 GPT 却找不到 Claude | Key 分组不含目标模型 | 检查 Key 分组与模型白名单 |
| 换了模型名还是旧报错 | 客户端缓存了旧模型条目 | 删除旧条目、刷新列表、重启客户端 |
| 只有某个功能 404 | 该功能走了模型不支持的接口 | 先跑纯文本最小请求定位 |
对照表给出的是方向，下面四个检查给出具体操作。建议按顺序走：地址错误最常见也最容易验证，权限问题最隐蔽所以放在模型名之后。
检查一：OpenAI 工具有没有带 /v1
OpenAI SDK、Codex 和多数桌面客户端的基础地址是 https://zivv.pro/v1。常见错误：
- 写成
https://zivv.pro，而客户端不会自动补/v1 - 写成
https://zivv.pro/v1/chat/completions，客户端又重复拼接一遍路径 - 多写一个斜杠，或复制时带进了不可见字符
不可见字符尤其阴险：从网页或聊天记录复制地址时，末尾可能跟着零宽空格，界面上完全看不出来。怀疑时把地址删掉，手动敲一遍这二十来个字符，比对着屏幕检查靠谱。
规则：基础地址只填到 `/v1`，具体接口路径由 SDK 或客户端补全。 判断方法也很简单：看客户端日志里最终请求的完整 URL，正确的对话请求应该落在 /v1/chat/completions，出现 /v1/v1/ 或缺少 /v1 都说明基础地址填错了。端点列表见 API 端点说明。
Claude Code 是例外，它走 Anthropic 协议：
export ANTHROPIC_BASE_URL=https://zivv.proClaude Code 的地址不要加 /v1；Gemini 协议则用 https://zivv.pro/v1beta。三种协议三种写法，混用是 404 的第一大来源。
检查二：模型名称是否准确
模型名称不是展示标题，大小写、连字符和版本号都参与匹配。比如 claude-opus-4-8 与 claude-opus-48、gemini-3.5-flash 与 gemini-3.5flash，一字之差就是 404。最稳妥的方式不是凭记忆输入，而是从接口或模型广场复制：
curl https://zivv.pro/v1/models \
-H "Authorization: Bearer sk-your-key"用 SDK 也可以把当前 Key 可用的模型全部打印出来：
from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://zivv.pro/v1")
for m in client.models.list():
print(m.id) # 从这里复制目标模型，别凭记忆手敲注意从返回的 id 字段复制，不要根据旧教程猜测新版本名称——模型会更新、迁移或停止提供，教程里的名字未必还在。
手敲模型名时的高频笔误还包括：版本号里的连字符和点号弄混（4-8 与 4.8）、漏掉或多打连字符、结尾多了一个空格、从网页复制时带进全角字符或不可见的零宽字符。这类错误在肉眼看来「明明一模一样」，但服务端做的是精确匹配。所以规则只有一条：永远复制，永远不手敲。
检查三：Key 分组是否支持该模型
同一个平台可能有多个接入分组，分别适合 Claude Code、OpenAI 兼容调用或其他场景。模型出现在公开列表里，不代表每个 Key 都有相同权限。到控制台检查创建 Key 时选的分组，并确认：
- 分组支持目标模型
- Key 没有模型白名单限制
- Key 没有过期或被禁用
- 目标模型不是仅供特定协议使用
一个典型信号：Key 能调 GPT 却找不到 Claude。这时应该先查分组和协议，而不是重装客户端——上面 models.list() 打印的就是这个 Key 实际可用的列表，比公开页面更权威。
如果确认是分组问题，两条路：换用分组内的等价模型，或者重新创建一个正确分组的 Key。比如专供 Claude Code 的分组走 Anthropic 协议，拿它的 Key 去调 OpenAI 兼容接口就可能查无此模型；反之亦然。创建 Key 时花五秒确认分组，能省掉之后半小时的排查。
检查四：客户端有没有保留旧模型
模型名称调整后，客户端下拉列表可能还存着旧值。按顺序处理：
- 刷新模型列表
- 删除旧的自定义模型条目
- 从模型广场复制新名称重新添加
- 重新选择服务商和模型
- 完全退出并重启客户端
注意第 5 步说的是退出进程，不是关掉窗口——不少客户端关窗后仍驻留在托盘或菜单栏，配置根本没有重载。重启后先发一句最小对话确认新模型生效，再恢复正常使用。
Codex 和自动化脚本还要检查项目配置、用户配置和环境变量是否同时定义了模型，多个来源互相覆盖时行为难以预测。保留一个明确来源，删掉其余的。
各客户端的高发点速查
Claude Code
ANTHROPIC_BASE_URL误加/v1是它 404 的第一大原因- 模型相关变量指定了已下线的版本时，也会表现为 not_found
Codex
- Base URL 忘带
/v1，或项目配置里写死了旧模型名 - 全局配置和项目配置同时存在时，先确认实际生效的是哪份
Cherry Studio 等桌面客户端
- 下拉列表里的旧模型条目没删，选中的还是已失效的名称
- 手动添加模型时名称与接口返回的
id不一致 - 完整配置流程见 Cherry Studio 接入教程
自动化脚本与服务端
- 模型名写死在代码常量或配置文件里，平台侧模型更新后没人同步
- 建议把模型名收敛到一处配置，并在启动时用
models.list()做一次自检，模型失效时快速失败并给出明确日志，而不是在业务请求里静默 404
最后：用最小请求确认
地址、模型、权限都核对后，发一个最小请求。先不要带长 Prompt、工具调用或图片：
curl https://zivv.pro/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{"model":"your-model-id","messages":[{"role":"user","content":"Reply OK"}]}'最小请求成功，说明平台、Key、地址和模型全部正常，剩下的问题一定在原客户端配置或请求内容里；最小请求失败，错误正文会直接告诉你卡在哪一环。
这套「最小化复现」的思路值得养成习惯：任何报错都先剥掉客户端、剥掉复杂参数，用最短路径确认基础链路，再逐项加回去。它对 404 有效，对 401、429 和各种奇怪的客户端行为同样有效——如果剥到 401 这一层，转去 401 排查指南继续。
常见问题 FAQ
Q：404 的请求会扣费吗？ A：不会。请求没有到达模型就被拒绝，不产生 Token 消耗。
Q：模型在广场里能看到，调用却 404，为什么？ A：多半是 Key 分组不含该模型，或该模型仅供特定协议。用 models.list() 看这个 Key 的真实可用列表。
Q：客户端只弹「请求失败」，怎么找到真实错误？ A：查客户端日志或调试面板，找原始响应；找不到就用本文的 curl 最小请求在终端直接复现。终端里拿到的状态码和错误正文，比任何弹窗都可靠。
Q：模型名会变吗，要不要定期检查？ A：会。模型有上新、迁移和下线，脚本里写死的模型名建议在报错时第一时间对照当前列表核对。
Q：换用新模型名后要改哪些地方？ A：把所有出现旧名称的位置列一遍：客户端下拉配置、环境变量、项目配置文件、代码常量、CI 的 Secret。漏掉任何一处都会让 404 看起来「时好时坏」。这也是建议把模型名收敛到单一配置来源的原因。
404 排查清单
- OpenAI 工具用
https://zivv.pro/v1，Claude Code 用https://zivv.pro - 模型名称从当前列表或模型广场复制
- Key 分组允许目标模型
- 清理客户端缓存的旧模型条目
- 用最小 curl 请求做终局验证
把这份清单收藏起来：下次再遇到 404，从第一条开始过，通常五分钟内就能定位。比起在客户端里反复点「重试」，一次系统性的排查省时得多，也顺便帮你把配置整理成了可复用的干净状态。
Codex 的完整配置见 Codex 接入指南，各错误字段含义见错误码说明。如果你还在选平台，Zivv 一个 Key 就能调 100+ 模型，三大协议全兼容，注册后按本文清单配置一遍，404 基本与你无缘。