トラブルシューティング
問題が発生したら？ここから始めましょう
まず症状から行き先を特定し、次に下のよくある問題を展開して照合しながら調査します。内容は重複させず、権威あるページへ案内するだけです。
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の後に空白が 1 つ） - 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）、発生時刻、再現手順。迅速な特定に役立ちます。