# 模型不可用

来源: https://platform.lyrouter.com/ai_gateway/docs/unavailable
更新日期: 2026-10-14

模型名写错、模型没有开通、没有可用的通道或凭证、余额不足，以及计费或配置暂时不可用，都会表现为模型调不通。请按响应中的报错原文在下表找到原因。工作空间在[智能路由](https://platform.lyrouter.com/ai_gateway/docs/routing)中设置了默认模型时，很多对话请求会改由默认模型回答，而不会收到这些错误；可以在日志的「模型（实际）」中确认。

## 按报错原文查找

| 状态码 | 报错原文（`error.message`） | `error.code` | 原因与处理 |
| --- | --- | --- | --- |
| 400 | `you must provide a model parameter` | `missing_model` | 请求没写 `model`，工作空间也没有设置默认模型。在请求中写上模型 ID |
| 400 | `invalid type for 'model': expected a string` | `invalid_model` | `model` 不是字符串。改成字符串形式的模型 ID |
| 400 | `This model does not support the <接口> API` | `unsupported_model_api` | 模型不支持当前接口，例如用对话模型调用图像生成接口。换用支持该接口的模型 |
| 400 | `This model accepts text input only` | `unsupported_model_input` | 给只接受文本的模型发送了图片、音频或文件。换用支持该输入的模型 |
| 402 | `insufficient credit balance` | `insufficient_credit_balance` 等 | 账户 Credits 余额不足，见下文「余额与订阅」 |
| 402 | `subscription expired; renew to continue` | — | 账户订阅已到期，见下文「余额与订阅」 |
| 403 | `Model is not available in the model plaza` | `model_not_available` | 工作空间没有开通该模型；或在图像、视频、语音接口上使用了虚拟模型或 `lyrouter/auto`。在模型广场开通模型，或改写具体的模型 ID |
| 503 | `all routed candidates exhausted` | `no_route_candidate` | 找不到可以服务这次请求的模型或通道。常见原因是 `@vmodel/<名称>` 写错或已停用，或者模型没有可用的通道或凭证 |
| 503 | `No configured credential can serve this model` | `no_route_candidate` | 模型的通道在本工作空间没有可用凭证：平台通道没有开通，或 BYOK 凭证都不可用 |
| 503 | `Platform supplier cost snapshot is unavailable` | `supplier_cost_snapshot_not_ready` | 服务这个模型的通道还没有配置好价格，网关无法计费。换用其他模型，并把模型 ID 告知支持人员 |
| 503 | `billing balance is temporarily unavailable` | `billing_maintenance` 等 | 网关暂时无法确认账户余额，这不是余额不足。持续出现时联系支持 |
| 503 | `Workspace model projection is unavailable` | `workspace_model_projection_unavailable` | 网关暂时读不到工作空间的模型配置，属于平台侧问题，稍后重试 |

BYOK 通道的价格未就绪时，报错原文为 `BYOK supplier cost snapshot is unavailable`。返回 500 或 504、且响应体是 HTML 页面时，说明连接上游失败或等待上游超时，见[超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors)。上游服务商自己返回的错误会原样转发，日志「状态说明」列的来源显示为「上游」。

（截图：检查模型是否启用、来源是否有效，以及当前身份是否可用。）

## 余额与订阅

| `error.code` | 含义 | 处理 |
| --- | --- | --- |
| `insufficient_credit_balance` | 账户余额已用完；使用 BYOK 且需要支付平台服务费时，余额不足以支付服务费 | 在 **订阅充值** 页面充值 |
| `balance_missing` | 账户还没有余额记录，通常是从未充值 | 充值；已充值仍出现时联系支持 |
| `billing_entity_missing` | 网关找不到 Key 对应的计费账户 | 平台侧数据问题，联系支持 |

- 余额检查发生在调用之前：余额大于 0 就可以发起调用，一次调用可能把余额扣成负数，之后的调用才会被拒绝。余额不足时，网关不会改用其他计费方式或其他通道。
- `subscription expired; renew to continue` 表示订阅已到期且已过宽限期，该账户下所有工作空间的调用都会被拒绝，续费后恢复。没有订阅的账户不会收到这个错误。
- 充值和续费由账户管理员操作，见[计费规则与信用点](https://platform.lyrouter.com/ai_gateway/docs/billing)和[购买、账单与发票](https://platform.lyrouter.com/ai_gateway/docs/orders)。

## 常见问题

### 提示模型不存在或不可用，怎样核对模型名？

**答：** 使用系统模型 ID，不要使用展示名称，也不要自己拼服务商前缀。用同一个 API Key 调用 [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models)，列表中是 Key 所属工作空间已开通、且安全围栏模型策略允许这个 Key 调用的模型 ID，以及已启用的 `@vmodel/<名称>` 和 `lyrouter/auto`。模型不在列表中，说明它没有开通或被策略禁止。虚拟模型和 `lyrouter/auto` 总会列出，实际选中的模型被策略禁止时，调用仍会返回 403。模型 ID 区分大小写。

### 模型已开通，为什么仍然返回 503？

**答：** 开通模型不等于有可用的凭证。请账号管理员在模型广场确认至少有一个服务来源处于有效状态；使用 BYOK 时，在 [BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok) 中检查凭证状态、模型映射，并重新测试连接。返回 `supplier_cost_snapshot_not_ready` 时是平台价格未就绪，需要联系支持。

### 配置了「仅用此 BYOK」，为什么没有回退到其他来源？

**答：** 这项设置限定该模型只使用指定通道的 BYOK 凭证，凭证全部失败后请求即结束，不会尝试平台凭证、其他通道或默认模型。请账号管理员检查该通道的凭证和映射，或在不需要独占时改为「优先使用此 Channel」，详见[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)。

### 更换模型后仍然失败，接下来检查什么？

**答：** 确认替代模型支持原请求的接口、输入类型和工具调用，再按报错原文对照上表。记录调用时间、模型、API Key 名称和报错原文，在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中找到这次请求，查看「状态说明」和日志详情顶部的 Request ID。