本文へスキップ
HopBase ドキュメント
ログイン

トラブルシューティング

プロトコル、キー、モデル、環境に関するエラーを素早く診断します。

カテゴリごとに該当する現象を探してください。ステータスコードの一覧、再試行のルール、問い合わせ時に必要な情報はエラーコードと再試行にまとめています。

ゲートウェイは Accept-Language ヘッダーに応じて簡体字中国語、繁体字中国語、英語、日本語、スペイン語のテキストを返し、指定がない場合は英語になります。各表は Accept-Language: ja のときに返る日本語の原文です。

キー、残高、権限

現象原因対処
401「API キーがありません」
「API キーが無効です」
「API キーの有効期限が切れています」		キーの未送信、コピー不完全、余分な空白、またはキーの削除・無効化・失効コンソールの API キー から完全なキーを再コピーし、必要なら新しく作成します
402「残高が不足しています」
「API キーのクォータを使い果たしました」
「メンバーのクォータを使い果たしました」
「部門のクォータを使い果たしました」		残高、キー、メンバー、部門のいずれかのクォータが不足チャージかクォータ調整の後に再送します。402 は自然に解消しないため、ループで再試行しないでください
動画送信で 402「Insufficient balance: available …」動画タスク送信時の残高引当が不足チャージしてから再送信します。ループで再試行しないでください
403「このアカウントは無効化されています」
「このメンバーアカウントは無効化されています」
「このメンバーには、この API キーに紐付けられたグループを利用する権限がありません」
「API キーがどのグループにも紐付けられていません。管理者にお問い合わせください」
「現在のグループでは画像生成が有効になっていません」		アカウント・メンバー・グループ設定による制限管理者に連絡します。再試行しないでください
404「この API キーが属するグループはオフラインになり、リクエストを受け付けなくなりました…」キーのグループが提供終了コンソールで提供中のグループのキーを作成し、置き換えます

モデルとパス

現象原因対処
404「現在のグループは要求されたモデルをサポートしていません：X」
「この API キーが属するグループでは、要求されたモデルを提供していません…」		モデル ID がキーのどのグループにもない、スペル誤り、または提供終了した ID が設定に残っているこのキーで GET /v1/models を呼び完全な ID をコピーします。一覧にない場合はそのモデルを含むグループをキーに追加し、自動再試行はしないでください
404「現在のプラットフォームではこの API パスはサポートされていません」Claude のキーで OpenAI プロトコルのエンドポイントを呼んだClaude は Anthropic プロトコルに切り替えます
同上Anthropic の Base URL に余分な /v1 が付き /v1/v1/messages になっているBase URL に /v1 を含めません
同上/v1/dashboard/billing/*、/v1/files、/v1/batches、/v1/embeddings など提供していないパスを呼んだ残高確認には GET /v1/usage かコンソールを使います
同上Codex のウェブ検索が /v1/alpha/search を呼んだこの 404 は通常の会話に影響しません
動画エンドポイントで 404「現在のプラットフォームではこの API パスはサポートされていません」動画のパスが間違っている動画 API に従い、POST /v1/video/generate で送信、GET /v1/video/tasks/{task_id} でポーリングします

リクエスト内容

現象原因対処
400「リクエストボディの読み取りに失敗しました」
「リクエストボディは正しいフィールド型を持つ JSON オブジェクトである必要があります」
「必須フィールド model がありません」
「messages は空でない配列である必要があります」		ボディが不完全、またはフィールドが不正JSON と Content-Type を確認します
413「リクエストボディがサイズ上限（60 MB）を超えています」ボディが 60 MB 超(多くは base64 の画像や動画)大きいファイルは圧縮するか、対応モデルなら 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 を使います
400「InputImageSensitiveContentDetected.PrivacyInformation」Seedance 2.0 が直接渡された実在人物の参照画像をプライバシー検出POST /v1/sd/assets で素材としてアップロードし、asset://asset-id で参照します。詳細は動画生成を参照
非同期タスクのポーリングが status: "failed" を返す(例:「the prompt was rejected by content moderation; rephrase it and submit again」)理由は error.message、code なし、課金なしメッセージに従って直してから再送信します。エラーコードと再試行を参照
非同期タスクの実際の課金額を知りたいタスク終了後の照会レスポンスに含まれるルートの usage.cost_usd(残高から差し引かれた米ドル額)・usage.cost(同じ課金額の人民元額)・usage.currency を読みます(課金なしの失敗は 0)。タスク一覧でも終了済みの各タスクの usage に同じ項目が含まれます。動画 APIを参照

レート制限、タイムアウト、切断

現象原因対処
429「ユーザーの同時実行数が上限に達しました。しばらくしてから再試行してください」
「API キーの同時実行数が上限に達しました。しばらくしてから再試行してください」		処理中のリクエストがアカウントかキーの同時実行上限を超過クライアント側でキューイングし、Retry-After に従って再送します。上限は同時実行数、タイムアウト、課金を参照
429「…は現在レート制限中です。しばらくしてから再試行してください」
502「…サービスは一時的に利用できません。しばらくしてから再試行してください」
503「現在利用可能な…がありません。しばらくしてから再試行してください」
503「リクエストを現在完了できません。しばらくしてから再試行してください」
504「…リクエストがタイムアウトしました。しばらくしてから再試行してください」
503「認証サービスは一時的に利用できません。再試行してください」		サービスが一時的に利用できないか、応答がタイムアウトRetry-After か指数バックオフで再試行するか、同系列の別モデルに切り替えます。10 分以上続く場合はレスポンスヘッダーの X-Request-ID を添えてお問い合わせください
503「この会話にひも付くステートフルセッションは再開できません…」元のセッションが再開不可previous_response_id を外して新しい会話を始めます
リクエストが途中で切断され、499 として記録される完了前にクライアントが切断(手動キャンセル、または読み取りタイムアウト。openai-python の既定は 600 秒)長い出力はストリーミングにし、読み取りタイムアウトを延ばします
ストリーミングの途中でエラーイベント(例:「Response stream interrupted, please retry」)が届く、または接続が切れる出力開始後の失敗のため、同じストリームでは再開できない受信済みの断片を破棄し、リクエスト全体を送り直します

ローカル環境

現象原因対処
"node / npm is not recognized"Node.js が未インストール、または PATH にないnodejs.org から再インストールし(Windows は既定の設定のまま)、ターミナルを開き直します
PowerShell でスクリプトの実行がブロックされるWindows の実行ポリシーによる制限コンソールのワンクリック接続コマンドを優先して使うか、管理者権限で Set-ExecutionPolicy RemoteSigned を実行します

表の手順で解決しない場合は、クライアント名、モデル ID、発生時刻のおおよそ、HTTP ステータスコード、レスポンスヘッダーの X-Request-ID、キーを隠したスクリーンショットを添えてお問い合わせください。

次のステップ

このページの内容

キー、残高、権限モデルとパスリクエスト内容画像と動画レート制限、タイムアウト、切断ローカル環境次のステップ