故障排查
遇到问题？从这里开始
先按症状定位去向，再展开下方高频问题对照排查。不重复内容，只把你导向权威页面。
API 报错（4xx / 5xx）
完整错误码、响应结构与重试策略 —— 401 / 402 / 404 / 429 / 5xx 一览。
账号、Key 与认证
注册、API Key 丢失、Key 无效排查、模型与流式调用常见问题。
计费与配额
免费额度、订阅计划、鹿贝扣费规则，以及配额耗尽后的处理。
客户端连不上
Cherry Studio / Lobe Chat / OpenCat 等第三方客户端的接入与排错。
产品专属问题
平台、MemX、Lucrum 等各产品均有独立 FAQ，先看对应产品文档的常见问题页。
返回 401 Unauthorized / invalid_api_key
json
{ "error": { "code": "invalid_api_key", "type": "authentication_error" } }authentication_error 表示 Key 无效或缺失。逐项检查：
- Key 完整、以
sk-开头、无多余空格或换行（重新复制一次） - 请求头格式
Authorization: Bearer sk-xxxx（Bearer后有一个空格） - Key 状态为「启用」（控制台 → 令牌管理）
- 环境变量名拼写正确且已加载
不要重试 401，直接修正 Key 后再发。详见 认证 与 常见问题：Key 无效怎么排查。
返回 "no available server" / model_not_found（HTTP 404）
json
{ "error": { "code": "model_not_found", "message": "模型 xxx 无可用渠道", "type": "new_api_error" } }- 检查
model名称拼写（区分大小写） - 确认该 Key 有权限访问此模型
- 该模型可能暂无可用渠道
- 如果刚创建 Key，等待约 10 秒后再试
可用模型清单见 支持的模型。
返回 429 Too Many Requests / rate_limit_exceeded
json
{ "error": { "code": "rate_limit_exceeded", "type": "rate_limit_error" } }超出速率限制。处理方式：
- 降低请求频率，按
2 ** attempt秒做指数退避后重试 - Free 默认 60 RPM，升级 Pro / Team 提高限额
- 付费后仍频繁触发，联系 support@lurus.cn
重试代码示例见 错误处理 · 最佳实践。
返回 402 / insufficient_quota（配额 / 余额不足）
json
{ "error": { "code": "insufficient_quota", "type": "billing_error" } }- 先确认是否已用完当天免费配额（Free 套餐 100 次/天）
- 查看鹿贝余额：identity.lurus.cn/wallet
- 自助充值或升级套餐，规则见 计费说明
context_length_exceeded（上下文超限）
json
{ "error": { "code": "context_length_exceeded", "type": "invalid_request_error" } }如 deepseek-chat 64K、gemini-3-pro-preview 1M，超出模型上限时：
- 减少输入、删减历史消息
- 用滑动窗口（保留 system + 最近 N 轮）
- 切换更长上下文的模型
请求超时 / 长时间无响应
- 检查网络连通：
curl https://hub.lurus.cn/v1/models - 减小
max_tokens - 推理模型（
deepseek-reasoner）思考时间长属正常 - SDK 默认超时约 60 秒，可调大
timeout - 持续超时可能为上游故障，换一个模型再试
没找到？联系 support@lurus.cn
请附上：错误信息完整内容、请求 ID（响应头
X-Request-ID）、发生时间、复现步骤，便于快速定位。