返回指南
故障排查·2026年7月17日·更新于 2026年9月30日·阅读约 6 分钟

model_not_found / 404——Claude、Gemini 和网关之间的模型命名

模型 ID 不可跨平台通用:api.anthropic.com 要求带日期的 ID,Gemini 使用自己的版本字符串,每个网关也定义自己的 slug。这里的 404 表示“此主机没有与该字符串完全匹配的模型”——解决方法始终是询问端点实际提供哪些模型。

最后审核于 。

模型 ID 不可跨平台通用:api.anthropic.com 要求带日期的 ID,Gemini 使用自己的版本字符串,每个网关也定义自己的 slug。这里的 404 表示“此主机没有与该字符串完全匹配的模型”——解决方法始终是询问端点实际提供哪些模型。

错误

响应(HTTP 404)
{
  "error": {
    "type": "model_not_found",
    "message": "The model 'claude-sonnet' does not exist or you do not have access to it.",
    "code": "model_not_found"
  }
}

原因和解决方法一览

原因解决方法
来自其他主机的模型 ID每个 API 都有自己的命名空间——从端点自身的模型列表复制 ID,不要从博客文章复制。
已弃用/重命名的版本提供商会停止提供带日期的快照;请固定到当前 ID,并订阅弃用通知。
拼写错误或被截断的 slugclaude-sonnet 在任何地方都不是一个模型;精确字符串很重要。
模型存在,但对你的密钥/套餐已禁用部分主机会根据套餐限制模型——列表端点会显示你的密钥能够调用的模型。

从正在调用的端点列出模型

GET /v1/models 是任何 OpenAI 兼容主机的事实依据——它会准确返回你的密钥可以使用的 ID:

list-models.sh
curl -s https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  | python3 -c "import json,sys; print('\n'.join(m['id'] for m in json.load(sys.stdin)['data']))"

在运行时解析模型,而不是硬编码

目录会发生变化(新增快照、停止提供旧版本)。在启动时解析模型列表,优先使用已配置的 slug 并准备后备方案;当配置的 slug 从 /v1/models 中消失时发出告警,而不是让生产环境出现 404。

如果你通过 Kunavo 调用

Kunavo 使用稳定、易读的模型 slug(claude-sonnet-5、gpt-5-6-terra、claude-fable-5),这些 slug 会在 GET /v1/models 中列出,并附带每个模型的元数据;已停止提供的 slug 会在网站模型页面通过 301 重定向到后继模型,因此链接不会失效。列表端点具有权威性——llms.txt 对任何读取它的代理也说明了同样的信息。

常见问题

为什么同一个模型 ID 在一个 API 上有效,在另一个 API 上却返回 404?

因为 ID 按主机划分命名空间:Anthropic 的带日期 ID、Gemini 的版本化名称以及各网关的 slug,对于相关模型来说都是不同的字符串。始终从目标端点自己的模型列表中复制。

如何防止模型退役带来的影响?

在启动时解析 /v1/models,将模型 ID 放在配置中(而不是代码中),定义回退链,并在配置的 ID 消失时通知自己——这样就能把生产环境中的 404 转化为配置变更。

相关指南

更多错误语义请参阅 错误参考;通过 注册 和 身份验证指南 获取密钥只需一分钟。