API 404 模型不存在怎么排查？
简答：照教程填了模型名却返回404，多半是模型ID、Base URL、接口协议或当前Key可用范围不匹配。先保存完整响应，再用同一API前缀请求模型列表并复制精确ID，最后用不带流式和工具调用的最小请求验证。PoloAPI当前目录与路径未核实，以其控制台或文档为准。
定义：“API 404 模型不存在”是服务端无法把当前请求路径、模型字段或资源标识匹配到可调用对象的表现，不等于模型一定已经下线。
先看响应：把404分成三类再处理
本文是独立整理的接入排障指南，不代表PoloAPI官方文档。遇到404时，先保存HTTP状态码、响应头、完整响应体、请求方法、最终请求URL，以及请求体里的model字段。不要只根据客户端显示的“模型不存在”四个字判断原因，因为网关可能把路径错误、模型错误和路由不可用显示成相似提示。
| 响应现象 | 优先判断 | 处理动作 |
|---|---|---|
| HTML页面、普通Not Found或路由不存在 | Base URL、版本段或资源路径不对 | 检查是否重复拼接/v1，并查看最终请求URL |
JSON包含model_not_found、模型不存在或资源不存在 | 模型ID、前缀、版本后缀或可用范围不匹配 | 先请求模型列表，再复制返回的精确ID |
| 模型列表可见，但生成请求提示模型不可用 | 接口协议、方法能力、项目权限或分组路由不匹配 | 使用同一前缀发起最小非流式请求 |
| 响应明确写“无可用渠道” | 模型字符串可能存在，但当前分组或路由没有可用上游 | 不要继续改模型名，核对分组、路由和服务端说明 |
| 返回401、403、402、429或503 | 认证、权限、计费、限流或服务端可用性问题 | 按状态码和响应体分流，不要统一当成404处理 |
官方接口也不是所有404都专指模型。Claude API错误说明把404定义为请求资源未找到，并要求检查请求路径和URL中的资源ID；同时，官方错误响应包含错误类型、消息和请求ID，可用于后续定位。
先试这一条命令：把API_PREFIX设置为服务要求的API前缀，并保持它在模型列表和生成请求中完全一致。
export API_PREFIX="https://你的API地址/v1"
export API_KEY="替换为你的Key"
curl "$API_PREFIX/models" \
-H "Authorization: Bearer $API_KEY"如果这个地址返回JSON，继续从返回结果中复制id字段；如果返回HTML，先修正地址或版本段。若服务要求不带/v1，就把API_PREFIX改成不含/v1的根地址，但不要在后续命令里再次自动追加。
用模型列表确认真实ID，不要照抄展示名称
模型的展示名称、模型ID、资源名和版本标识可能不是同一字符串。调用时应优先使用模型列表返回的精确值，逐项检查大小写、连字符、下划线、版本后缀、前后空格，以及是否误把资源名格式填入只接受模型ID的字段。
OpenAI官方参考提供了列出模型的接口，模型列表可用于确认当前账号能够看到的模型资源，详见OpenAI List models。这可以作为OpenAI兼容接口的排查依据，但不能据此断定每个兼容服务的路径完全相同。
Anthropic官方模型参考同样提供GET /v1/models和按模型ID获取信息的接口，返回内容还包含模型能力等字段，可查看Claude Models API。Google的官方模型接口也说明，模型列表可以程序化获取可用模型及其支持能力，详见Gemini Models API。
因此，正确顺序应是：
- 确认当前Key和API前缀。
- 请求当前服务的模型列表。
- 复制返回的精确
id或服务要求的模型资源名。 - 把它原样放到请求体顶层的
model字段。 - 先用短文本、非流式请求验证，再恢复高级参数。
如果模型列表接口返回401、403、空数组或HTML，不要继续猜模型名。先判断是Key无效、权限受限、接口不提供列表，还是URL没有进入API路由。检索到的PoloAPI公开模型示例页中曾出现模型ID、代码模板和错误说明，但该页面的当前性与域名归属未核实，不能把其中的模型名直接当作当前可用目录；需要核对其当前控制台或文档，参考页可见检索到的PoloAPI模型示例页。
统一Base URL：模型列表成功后，生成请求也用同一前缀
最容易复现的路径错误是模型列表使用了一个前缀，生成请求却换成另一个前缀。例如GET /v1/models成功，但调用时写成/chat/completions；或者Base URL本身已经包含/v1，客户端又自动追加一次，形成/v1/v1/...。
建议先把“服务地址前缀”和“资源路径”拆开。下面的示例假定模型列表成功地址是$API_PREFIX/models，那么聊天请求就应使用同一个$API_PREFIX/chat/completions：
curl "$API_PREFIX/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "替换为模型列表中的真实ID",
"messages": [
{"role": "user", "content": "只回复：ok"}
],
"stream": false
}'model必须位于请求体顶层，并且是字符串。第一轮测试不要同时加入工具调用、图片、长上下文、思考参数或流式输出。最小请求成功后，再一次只恢复一个功能，这样才能知道是哪一项配置造成新的错误。
协议也需要匹配。OpenAI Chat Completions、OpenAI Responses和Anthropic Messages的路径、请求体以及返回结构并不相同。Google官方的Gemini OpenAI兼容说明明确展示了兼容层自己的baseURL和chat/completions路径，并提醒兼容层不等同于原生接口。由此可见，只改模型名或只改URL，不能保证另一种协议的请求体仍然适用。
把“模型不存在”和“无可用渠道”分开处理
中转或路由服务可能返回类似“当前分组下对于模型某某无可用渠道”的提示。这个现象与模型ID拼写错误不同：它通常表示服务端已经识别到模型字符串，但当前Key、分组、路由或上游渠道没有可用匹配。因为不同平台的错误结构和状态码并不统一，不能仅凭一句提示断定具体是额度、路由配置还是上游暂时不可用。
| 状态或文本 | 不要误判为 | 建议动作 |
|---|---|---|
model_not_found或明确模型不存在 | 服务整体故障 | 重新列出模型，检查精确ID、前缀和版本后缀 |
| HTML 404、Not Found | 模型已下线 | 检查Base URL、/v1和资源路径是否重复或缺失 |
| 无可用渠道、模型不可用 | 一定是模型名拼错 | 保留当前模型ID，核对Key分组、路由和服务端说明 |
| 401或403 | 继续换模型即可解决 | 检查Key、项目、工作区和分组权限 |
| 402、429、503或服务自定义错误 | 一定是404模型问题 | 按响应体确认计费、限流、容量或上游状态 |
以官方Claude API为例，错误文档将401归为认证问题、402归为计费问题、403归为权限问题、429归为速率或支出限制，503并不是其通用模型不存在定义；具体可查看Claude API错误码说明。其他服务可能使用不同映射，因此本文只把状态码作为分流线索，最终以当前服务返回体和文档为准。
如果模型已经从列表中消失，或者模型信息显示已退休、已弃用，就不要继续使用旧教程中的字符串。官方模型生命周期页面会记录模型状态和迁移方向，可参考Claude模型生命周期说明。PoloAPI当前的模型下线记录、分组规则、余额规则和可用渠道状态均未核实，本文不对此作结论。
确认客户端最终发送了什么：Python、Node.js和日志排查
只看配置文件不够，因为SDK可能自动补全路径、覆盖模型名或切换请求端点。排查时至少要确认四项：最终请求方法、最终URL、请求体中的model、实际使用的协议。先用curl复现，再回到SDK，通常更容易判断问题在服务端还是客户端。
OpenAI官方Python SDK支持通过OPENAI_LOG=debug启用更详细日志；官方Node.js SDK也支持环境变量或客户端logLevel配置，说明见OpenAI Python SDK和OpenAI Node.js SDK。日志可能包含请求元数据或业务内容，复制给他人前应脱敏Key、Authorization头、提示词和响应内容。
# Bash
export OPENAI_LOG=debug
python your_script.py
# Node.js
OPENAI_LOG=debug node your_script.mjsPython最小验证模板：
import os
from openai import OpenAI
api_key = os.getenv("API_KEY")
base_url = os.getenv("API_PREFIX")
if not api_key or not base_url:
raise SystemExit("请先设置 API_KEY 和 API_PREFIX")
client = OpenAI(
api_key=api_key,
base_url=base_url.rstrip("/")
)
models = client.models.list()
for item in models.data:
print(item.id)
response = client.chat.completions.create(
model="替换为模型列表中的真实ID",
messages=[{"role": "user", "content": "只回复：ok"}],
stream=False
)
print(response.choices[0].message.content)Node.js最小验证模板：
import OpenAI from "openai";
const apiKey = process.env.API_KEY;
const baseURL = process.env.API_PREFIX;
if (!apiKey || !baseURL) {
throw new Error("请先设置 API_KEY 和 API_PREFIX");
}
const client = new OpenAI({
apiKey,
baseURL: baseURL.replace(/\/$/, ""),
logLevel: "debug"
});
const models = await client.models.list();
for await (const item of models) {
console.log(item.id);
}
const response = await client.chat.completions.create({
model: "替换为模型列表中的真实ID",
messages: [{ role: "user", content: "只回复：ok" }],
stream: false
});
console.log(response.choices[0].message.content);如果SDK日志看不到最终URL，可以用本地反向代理或抓包工具观察请求行；测试环境中也可以先使用可控的HTTP代理记录方法、路径和状态码。不要把Bearer Key放进命令历史、进程参数或公开日志；排查结束后应清理调试日志。
常见问题
API返回404就一定是模型不存在吗？
不一定。HTML 404或普通Not Found更像是Base URL、版本段或资源路径错误；响应体明确包含模型资源错误时，才优先检查模型ID、权限和生命周期。
为什么模型列表里有模型，调用仍然返回404？
可能是列表接口与生成接口的协议不同、模型不支持当前方法、客户端重复拼接了/v1，也可能是列表权限与生成权限不同。使用同一API前缀发起不带流式和工具调用的最小请求，并记录最终URL。
模型ID前面要不要加models/？
不能一概而论。Google原生模型资源使用models/{model}格式，而某些OpenAI兼容接口的model字段只接受模型ID。应以当前接口文档和模型列表返回值为准，不要自行拼接前缀。
出现“无可用渠道”还要继续换模型吗？
先不要。保留模型ID，检查当前Key所属分组、路由和服务端可用性；如果模型列表能看到而生成请求仍提示无渠道，问题更可能在当前路由或权限范围，而不是简单拼写错误。
返回403、余额不足或429，还要继续换模型吗？
通常不应先换模型。403优先检查权限，余额或计费提示按控制台处理，429优先检查限流和并发。只有认证、权限和额度确认后，才继续判断模型是否可用。
能否直接使用网上教程里的模型名？
不建议。模型ID、版本后缀、生命周期和能力可能变化。优先使用当前模型列表返回的精确字符串；无法获取列表时，应到当前平台控制台或文档核对。
常见问题
API返回404就一定是模型不存在吗？
不一定。HTML 404或普通Not Found更像是Base URL、版本段或资源路径错误；响应体明确包含模型资源错误时，才优先检查模型ID、权限和生命周期。
为什么模型列表里有模型，调用仍然返回404？
可能是列表接口与生成接口的协议不同、模型不支持当前方法、客户端重复拼接了/v1，或列表权限与生成权限不同。请使用同一API前缀发起最小请求并记录最终URL。
模型ID前面要不要加models/？
不能一概而论。Google原生模型资源使用models/{model}格式，部分OpenAI兼容接口的model字段只接受模型ID。以当前接口文档和模型列表返回值为准。
出现“无可用渠道”还要继续换模型吗？
先不要。保留模型ID，检查当前Key所属分组、路由和服务端可用性；模型列表能看到但生成请求提示无渠道时，问题更可能在当前路由或权限范围。
返回403、余额不足或429，还要继续换模型吗？
通常不应先换模型。403优先检查权限，余额或计费提示按控制台处理，429优先检查限流和并发。确认认证、权限和额度后，再判断模型是否可用。
能否直接使用网上教程里的模型名？
不建议。模型ID、版本后缀、生命周期和能力可能变化。优先使用当前模型列表返回的精确字符串；无法获取列表时，到当前平台控制台或文档核对。