常见问题

使用 API Key 调用返回 401 authentication_failed

可能原因：

• API Key 粘贴错误。
• API Key 对应的令牌已停用或已删除。
• 请求头未使用 Authorization: Bearer {API_KEY}。

处理方法：

1. 在 令牌管理 中确认令牌状态。
2. 重新复制业务系统中的配置。
3. 使用 cURL 示例验证。

调用返回 403 model_access_denied

可能原因：

• 令牌未授权目标模型。
• 用户或组织没有模型访问权限。

处理方法：

1. 检查令牌的模型范围。
2. 检查组织模型访问规则。
3. 保存后重新调用。

调用返回 503 no_available_channel

可能原因：

• 渠道未启用。
• 渠道未同步模型。
• 模型未启用。
• 路由策略指向不可用渠道。

处理方法：

1. 在 渠道管理 中确认渠道启用。
2. 执行 同步模型。
3. 启用目标模型。
4. 检查路由策略。

调用返回 429

可能原因：

• 令牌额度不足。
• 用户或组织预算不足。
• 触发请求限流。

处理方法：

1. 查看 用量日志 和 配额管理。
2. 调整预算或额度。
3. 如为突发流量，检查限流策略是否合理。

流式请求卡顿或中断

可能原因：

• 上游模型服务响应慢。
• 入口代理缓冲了 SSE。
• 文件句柄或连接池不足。

处理方法：

1. 查看 /metrics 中活跃流和数据库连接池指标。
2. 检查 Nginx 或 Ingress 是否关闭响应缓冲。
3. 检查服务进程文件句柄上限（open files）。
4. 查看脱敏后的上游失败诊断文件。