常见错误码
调用 KOPRouter API 时可能遇到以下错误码。每个错误码下方列出了含义、常见原因与解决方案。
鉴权失败：API Key 缺失、无效或已失效。
**常见原因**
* 请求未携带 `Authorization: Bearer` 头
* API Key 拼写错误或已被删除 / 禁用
* Key 与账号不匹配
**解决方案**
确认请求头正确、Key 完整，并在控制台「密钥管理」中检查 Key 状态，必要时重新生成。
余额不足：预付费余额或订阅额度不足以支付本次请求。
**常见原因**
* 预付费余额已用尽
* 订阅额度用完且未开启按量付费
* 请求预估费用超过剩余额度
**解决方案**
在控制台充值，或等待订阅额度刷新后重试。
无权限：当前账号或用户组无权访问该模型或资源。
**常见原因**
* 模型未对你的用户组开放
* 超出用户组 / Token 配额上限
* IP 或渠道被限制
**解决方案**
检查你的用户组权限与配额，联系管理员开通对应模型。
资源不存在：模型 ID 或端点路径无效。
**常见原因**
* `model` 填写了 `/v1/models` 列表之外的 ID
* 端点路径拼写错误
**解决方案**
用 `/v1/models` 返回的 `id` 原样填充 `model` 字段，核对端点路径。
触发限流：请求频率超过阈值。
**常见原因**
* 超出 IP / Token / 用户组的速率限制
* 瞬时并发过高
**解决方案**
降低请求频率或并发，采用指数退避重试。
上游错误：网关转发到上游供应商时失败。
**常见原因**
* 上游供应商临时不可用
* 渠道故障或超时
**解决方案**
KOPRouter 会自动故障转移；如持续出现，请稍后重试或联系支持。