模型不可用

请求返回“模型不存在”“模型不可用”“无权访问模型”或 model_not_found 时，不一定表示平台上完全没有这个模型。模型 ID、API 密钥分组、密钥模型范围、接口端点和模型当前状态中的任何一项不匹配，都可能产生类似错误。

快速判断

先根据现象确定优先检查项：

现象	优先检查
所有模型都不可用	API 密钥状态、鉴权、账户余额和请求地址
只有一个模型不可用	模型 ID、分组、密钥模型范围和模型当前状态
模型列表中没有目标模型	当前密钥分组、模型限制、查询协议和平台模型状态
模型列表中存在，但生成请求失败	生成端点是否匹配、请求体格式、模型能力和上游状态
Chat Completions 可用，Responses 不可用	模型可能只支持 `Chat` 端点，不支持 `Response`
在控制台可见，但 API 查询不到	模型广场展示范围与当前密钥的实际权限不同
之前可用，突然不可用	密钥或分组被修改、模型渠道调整、模型下线或临时故障
第三方工具中找不到，直接请求可用	工具的模型缓存、服务商配置或模型别名没有更新

建议不要一开始就反复重试或更换多个配置。先保存错误消息，再查询当前密钥实际可用的模型列表。

第一步：记录实际错误

排查前记录以下信息：

HTTP 状态码。
响应体中的完整错误消息和错误代码。
请求使用的模型 ID。
请求接口，例如 /v1/chat/completions、/v1/responses、/v1/messages 或 /v1beta/...。
使用的 API 密钥名称和分组；不要记录完整密钥。
请求时间和时区。

常见状态码只能作为线索：

状态码	可能含义
`400`	模型或参数不受当前端点支持
`403`	密钥有效，但分组或模型范围不允许调用
`404`	模型 ID 不存在、当前密钥不可见，或请求路径错误
`429`	模型负载受限、请求频率过高，或账户与密钥额度不足
`500`、`502`、`503`、`504`	模型渠道或上游服务暂时异常

同一个状态码可能有多种原因，应以错误消息和控制台使用日志为准。

第二步：查询当前密钥的模型列表

使用发生问题的同一枚 API 密钥查询模型，不要改用另一枚密钥测试：

curl "https://www.bita-api.com/v1/models" \
  -H "Authorization: Bearer $BITA_API_KEY"

OpenAI 兼容响应中的 data[].id 是当前密钥可使用的模型 ID。判断结果如下：

目标模型不在列表中

依次检查：

API 密钥所属分组是否支持该模型。
密钥是否设置了单独的模型范围。
模型广场中的模型 ID 是否复制完整。
模型当前是否仍处于启用状态。
使用 Anthropic 或 Gemini 工具时，是否通过对应协议查询了模型。

模型广场展示平台当前提供的模型，/v1/models 返回当前 API 密钥实际可访问的模型。两者的范围不同，最终应以当前密钥查询结果和实际调用为准。

目标模型在列表中

说明模型 ID 和基础权限大概率正确，继续检查：

生成请求使用的端点是否为模型支持的类型。
请求体是否属于该端点的协议格式。
第三方工具是否实际发送了列表中的完整模型 ID。
模型是否只在某种兼容接口下可用。
当前模型渠道是否发生临时异常。

不同协议的模型查询方式参见查询可用模型。

检查模型 ID

请求中的 model 必须与模型列表返回的 id 完全一致。常见错误包括：

使用模型的中文名称、系列名称或供应商名称代替模型 ID。
根据印象手动输入，遗漏版本号、日期、连接符、斜杠或后缀。
修改了大小写。
复制时带入首尾空格、引号或换行。
第三方工具显示了友好名称，但实际发送的是另一个模型别名。
把其他平台上的模型 ID 直接用于 Bita API。

正确做法是从 /v1/models 的 data[].id 或模型广场的复制按钮获取完整 ID：

{
  "model": "从模型列表复制的完整 ID"
}

不要自行“修正”模型名称

模型 ID 中的 /、-、.、日期和版本后缀都可能是名称的一部分。不要为了适配客户端而删除字符；如果客户端不接受该 ID，应检查客户端是否支持自定义模型名称。

检查 API 密钥分组

API 密钥只能调用其所属分组内可用的模型。模型在模型广场可见，不代表 default、claude-origin、gpt-origin 等所有分组都能调用。

排查步骤：

在 API 密钥列表中确认当前客户端使用的是哪一枚密钥。
查看该密钥所属分组。
在模型广场筛选同一分组。
确认目标模型在该分组下可用。
再使用这枚密钥查询 /v1/models。

如果分组不匹配，建议为目标分组单独创建一枚 API 密钥，并给密钥使用容易识别的名称。不能通过修改请求中的 model 或伪造分组参数绕过权限。

“模型无限制”不等于可以调用全部模型

密钥显示“模型无限制”只表示没有额外设置模型白名单。密钥仍然受所属分组、平台模型状态和接口端点限制。

更多说明参见 API 密钥权限与额度限制。

检查接口端点

同一个模型名称可能只支持部分端点。能够通过一种接口调用，不表示可以直接换到另一种接口。

模型广场端点类型	常用接口	主要输入字段
`Chat`	`/v1/chat/completions`	`model`、`messages`
`Response`	`/v1/responses`	`model`、`input`
`Anthropic`	`/v1/messages`	`model`、`messages`、`max_tokens`
`Gemini`	`/v1beta/models/MODEL_ID:generateContent`	`contents`

典型的端点不匹配包括：

模型只标记为 Chat，却请求 /v1/responses。
Claude 模型可以通过 Anthropic Messages 调用，但工具实际发送的是 Responses 请求。
Gemini 原生客户端使用 /v1beta，却配置了只适用于 OpenAI 兼容接口的模型名称或请求体。
第三方工具固定使用某种协议，而所选模型没有对应端点。

应先在模型广场确认目标模型的端点类型，再选择对应 SDK 或第三方工具。接口之间不能只靠修改 URL 互相转换，请求体和响应结构也必须匹配。

发送最小请求

如果目标模型支持 Chat，可以用最小请求排除第三方工具配置和高级参数的影响：

curl "https://www.bita-api.com/v1/chat/completions" \
  -H "Authorization: Bearer $BITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "回复 ok"}
    ],
    "stream": false
  }'

将 YOUR_MODEL_ID 替换为模型列表返回的准确 ID。

最小请求成功：问题通常位于第三方工具配置、模型缓存或额外参数。
最小请求仍提示模型不可用：继续检查分组、端点和使用日志。
最小请求返回参数错误：确认该模型是否支持 Chat，并改用模型标注的接口。

第三方工具中的模型不可用

第三方工具可能缓存模型列表，或者用内部别名覆盖填写的模型 ID。直接 API 请求成功但工具失败时，检查：

工具当前启用的服务商是否为 Bita API。
Base URL 是否符合该工具要求，尤其检查 /v1 是否重复或遗漏。
API 密钥是否与命令行测试使用的是同一枚。
模型输入框中是否保存了完整模型 ID，而不是显示名称。
工具使用 Chat、Responses、Anthropic 还是 Gemini 协议。
是否需要点击“获取模型”“刷新模型”或手动添加模型。
修改配置后是否完全退出并重新启动了工具。

如果工具会自动选择小模型、后台模型或模型别名，还要分别检查这些映射。例如主对话模型可用，不代表后台任务配置的另一个模型也可用。

地址问题参见 Base URL 与 /v1 路径问题，具体工具配置参见第三方接入。

模型之前可用，现在不可用

模型和上游渠道可能更新、维护或下线。遇到突然失败时：

重新查询模型列表，确认模型是否仍对当前密钥可见。
检查 API 密钥状态、有效期、分组和模型范围是否被修改。
在使用日志中对比最后一次成功和第一次失败的时间、模型及分组。
使用同分组中的另一个确认可用模型发送最小请求。
如果只有一个模型返回 5xx 或负载错误，短暂等待后有限重试。

如果模型已经不在列表中，不要继续对原模型无限重试。应从当前模型列表选择替代模型，并根据新模型支持的端点调整客户端配置。

哪些情况适合重试

错误类型	处理方式
模型 ID 错误	修正 ID 后再请求，不要原样重试
分组或权限不匹配	更换正确分组的密钥或调整权限，不要原样重试
端点不匹配	更换正确接口和请求格式，不要原样重试
模型已下线	选择替代模型
`429` 频率或并发限制	降低请求速度，遵循 `Retry-After` 或使用指数退避
`500`、`502`、`503`、`504`	等待后有限重试，并设置最大次数
余额或密钥额度不足	补充余额或调整额度，等待本身不能解决

对持续的 403、404 或 model_not_found 无限重试不会使模型恢复，还可能产生大量无效日志。

排查清单

仍无法调用时，按顺序确认：

请求中的模型 ID 来自当前密钥的模型列表。
模型 ID 大小写、符号和版本后缀完全一致。
API 密钥已启用、未过期且仍有可用额度。
密钥分组和模型范围允许调用目标模型。
请求接口与模型端点类型匹配。
请求体使用了当前协议的字段结构。
Base URL 没有重复或遗漏 /v1、/v1beta。
第三方工具没有使用旧模型缓存或其他密钥。
使用日志中的实际模型、分组和错误与客户端一致。

反馈问题时，请提供请求时间和时区、模型 ID、接口路径、HTTP 状态码、完整错误消息、API 密钥名称及分组，以及脱敏后的最小请求。不要提供完整 API 密钥。

其他错误码参见常见错误码，余额和限流问题参见余额、额度与限流问题。

快速判断​

第一步：记录实际错误​

第二步：查询当前密钥的模型列表​

目标模型不在列表中​

目标模型在列表中​

检查模型 ID​

检查 API 密钥分组​

检查接口端点​

发送最小请求​

第三方工具中的模型不可用​

模型之前可用，现在不可用​

哪些情况适合重试​

排查清单​