HopBase ドキュメントトラブルシューティング
プロトコル、キー、モデル、環境に関するエラーを素早く診断します。
該当する現象の行を探してください。ステータスコードの一覧、再試行のルール、問い合わせ時に必要な情報はエラーコードと再試行にまとめています。ゲートウェイは Accept-Language ヘッダーに応じて中国語・英語などのテキストを返し、ヘッダーが指定されていない場合は英語がデフォルトになります。
| 症状 | 原因 | 対処 |
|---|---|---|
| 401「缺少 API Key」/「API Key 无效」/「API Key 已过期」 | キーが送信されていない、コピーが不完全または余分な空白が入っている、あるいはキーが削除・無効化・失効している | コンソールの API キー から完全なキーを再度コピーしてください。必要であれば新しく作成します |
| 402「余额不足」/「API Key 配额已用完」;動画送信では「Insufficient balance: available …」が返ります | アカウント残高、このキーのクォータ、または動画タスク送信時の残高引き当てが不足しています | 再試行の前にチャージするか、キーのクォータを調整してください。402 は自然には解消しないため、ループで再試行しないでください |
| 429「用户并发已达上限，请稍后重试」/「API Key 并发已达上限，请稍后重试」 | 同時に処理中のリクエストが、アカウントまたはキーの同時実行数の上限を超えています | クライアント側でリクエストをキューイング・制限し、レスポンスヘッダーの Retry-After に従って再試行してください。上限の詳細は同時実行数、タイムアウト、課金を参照してください |
| 429「…当前受到限流，请稍后重试」 502「…服务暂时不可用，请稍后重试」 503「当前没有可用的…，请稍后重试」/「请求暂时无法完成，请稍后重试」 504「…请求超时，请稍后重试」 | モデルが一時的に利用できないか、応答がタイムアウトしています | Retry-After または指数バックオフで再試行するか、同系列の別モデルに切り替えてください。10 分以上続く場合は、レスポンスヘッダーの X-Request-ID を添えてお問い合わせください |
| リクエストが処理中に切断され、499 として記録される | 完了前にクライアント側が切断しています。手動でのキャンセル、またはクライアント自身の読み取りタイムアウトが先に発生した場合です(openai-python のデフォルトは 600 秒、他のクライアントは異なります) | 長い出力にはストリーミングを使用し、クライアントの読み取りタイムアウトを延ばしてください |
| ストリーミング応答の途中でエラーイベントが届く(例:「Response stream interrupted, please retry」)、または接続が切断される | 出力が始まった後に失敗しているため、同じストリームでは再開できません | それまでに受信した部分的な出力を破棄し、リクエスト全体を送り直してください |
| 404「当前分组不支持所请求的模型：X」/「该 API Key 所属分组未提供所请求的模型…」;400「… is not a valid model ID」 | モデル ID がこのキーのプランに含まれていない、スペルが間違っている、またはクライアント設定に提供終了した ID がキャッシュされたまま残っています | このキーで GET /v1/models を呼び、レスポンスから完全な ID をコピーしてください。一覧にない場合は、そのモデルを含むプランのキーに切り替えてください。自動での再試行はしないでください |
| 404「Model "X" is not supported by any configured account in this group」 | このプランでは現在そのモデルがリクエストを処理できません | まずこのキーで GET /v1/models を呼んでください。一覧にモデルがある場合は、上記の 502 / 503 と同様に扱ってください。ない場合は、モデル ID を切り替えるか、別のプランのキーを使用してください |
| 404「当前平台不支持该 API 路径」 | パスがこのキーのプランに属していません:Claude のキーで OpenAI プロトコルのエンドポイントを呼んだ、Anthropic の Base URL に余分な /v1 が付き /v1/v1/messages になっている、あるいは /v1/dashboard/billing/*、/v1/files、/v1/batches、/v1/embeddings、Codex のウェブ検索用 /v1/alpha/search など、プラットフォームが提供していないパスを呼んでいます | Claude は Base URL に /v1 を含めない Anthropic プロトコルに切り替えてください。残高確認には GET /v1/usage またはコンソールを使用してください。ウェブ検索の 404 は通常の会話には影響しません |
| 動画エンドポイントで 404「当前平台不支持该 API 路径」が返る | 動画のパスが間違っています | 動画 API の手順に従い、POST /v1/video/generate で送信し、GET /v1/video/tasks/{task_id} でポーリングしてください |
| 400「读取请求体失败」;413「请求体超过大小限制（60 MB）」 | リクエストボディが不完全、または 60 MB を超えています(多くは base64 エンコードされた画像や動画) | JSON と Content-Type を確認してください。大きいファイルは先に圧縮するか、モデルが対応していれば URL を渡してください |
| 400 コンテキスト長超過(具体的な文言はモデルによって異なります) | 会話履歴、添付ファイル、max_tokens の合計がモデルのコンテキストウィンドウを超えています | 履歴を削るか新しい会話を開始し、max_tokens を小さくしてください |
400「Invalid signature in thinking block」/「duplicate thinking.signature」 | Claude の thinking 履歴が書き換えられた、結合された、または重複しています | 直前の assistant ターンの thinking ブロックを、signature を含めて受け取ったとおりにそのまま返してください。書き換えや結合、モデルをまたいだ再利用はしないでください。解決できない場合は、thinking 履歴を含まない状態で会話をやり直してください |
| 400「No tool call found for function call output」/「No tool output found for function call」 | ツールの実行結果と呼び出しがペアになっていません:tool_call_id / call_id が一致していない、またはどちらかが欠けています | 各ツール呼び出しに対して結果を必ず 1 つだけ返し、ID はそのまま返してください。履歴を削る際は、ペアの両方をまとめて削除してください |
| 400「Unsupported parameter: …」 | 送信したパラメータをそのモデルが受け付けません | 該当パラメータを削除してください。Responses API では、出力長の制限に max_tokens ではなく max_output_tokens を使用してください |
| 400 コンテンツがセーフティポリシーに拒否される(例:「Your request was rejected by the safety system.」) | プロンプトまたは参照素材が、モデルのコンテンツセーフティポリシーに抵触しています | 再送する前にプロンプトまたは素材を修正してください。同じ内容のまま再送しても再度拒否されます |
| 400 画像パラメータが不正(例:「size … is not valid」) | サイズ、グレード、枚数がそのモデルの対応範囲外です | 画像生成 API を参照し、そのモデルに合わせて値を調整してください |
| 400「media_download_failed」 | 参照用の画像・動画の URL に一般公開の状態でアクセスできません | サインインなしでダウンロードできる HTTP(S) の URL を使用してください |
| 404「该 API Key 所属分组已下线，不再处理请求…」 | このキーが属するプランは提供を終了しています | コンソールで現在販売中のプランのキーを新しく作成し、置き換えてください |
| 400「InputImageSensitiveContentDetected.PrivacyInformation」 | Seedance 2.0 は、リクエストに直接渡された実在人物の参照画像に対してプライバシー検出を行います | まず POST /v1/sd/assets で素材としてアップロードし、asset://asset-id の形式で参照してください。詳細は動画生成を参照してください |
| "node / npm is not recognized" | Node.js がインストールされていないか、PATH に含まれていません | nodejs.org から再インストールし(Windows では既定の設定のまま進めてください)、ターミナルを閉じて開き直してください |
| PowerShell でスクリプトの実行がブロックされる | Windows の実行ポリシーによる制限です | コンソールのワンクリック設定コマンドの利用を優先してください。または管理者権限で Set-ExecutionPolicy RemoteSigned を実行してください |
この表で解決しない場合は、クライアント名、モデル ID、発生時刻のおおよそ、HTTP ステータスコード、レスポンスヘッダーの X-Request-ID、キーを隠したスクリーンショットを添えてお問い合わせください。