HopBase ドキュメントエラーコードと再試行
HopBase のエラーレスポンス構造、各ステータスコードの意味と再試行可否、ストリーミング時の失敗の見え方、問い合わせ時に必要な情報。
症状から素早く調べる場合はエラー早見表を、本ページは全体の基準としてご利用ください。同時実行数の上限・タイムアウト・課金は同時実行数、タイムアウト、課金にあります。
エラーレスポンスの構造
OpenAI プロトコル（/v1/chat/completions、/v1/responses、/v1/images/*、/v1/video/*）:
{ "error": { "message": "…", "type": "invalid_request_error", "code": "insufficient_quota" } }Anthropic プロトコル（/v1/messages）:
{ "type": "error", "error": { "type": "invalid_request_error", "message": "…" } }メッセージの言語はリクエストヘッダー Accept-Language に従い、指定がない場合は英語です。プログラムでは HTTP ステータスコードと code で判定し、メッセージ本文で分岐しないでください。
ステータスコード
| コード | 主な原因 | 再試行 | 対処 |
|---|---|---|---|
| 401 | キー未指定、コピー漏れ、無効化済み、期限切れ | 不可 | コンソールの「API キー」から再取得するか、新規作成します |
| 402 | 残高切れ、キーのクォータ切れ、動画送信時の残高引当不足 | チャージ後に可 | チャージまたはキーのクォータを調整します。ループでの再試行は避けてください |
| 403 | プランがクライアントを制限している、または機能が未開通 | 不可 | そのプランで利用できるクライアントまたはプランに変更します |
| 404 | モデルがこのキーのプランに無い、パスが対象外、プランが提供終了 | 不可 | このキーで GET /v1/models を呼び ID を確認します。パスはBase URL とプロトコルを参照 |
| 413 | リクエストボディが 60 MB 超 | 不可 | 素材を圧縮するか、モデルが対応していれば URL を渡します |
| 429 | アカウントまたはキーの同時実行上限、あるいは当該モデルが一時的に制限中 | 可 | Retry-After に従って再試行し、同時実行数を下げます |
| 499 | 完了前にクライアントが切断（手動中断または読み取りタイムアウト） | 可 | 長い出力はストリーミングにし、クライアントの読み取りタイムアウトを延ばします |
| 502 / 503 | モデルが一時的に利用できず、自動リトライでも復旧せず | 可 | 間隔を空けて再試行するか、同系列の別モデルに切り替えます |
| 504 | 処理がタイムアウト | 可 | 間隔を空けて再試行します。長時間の処理はストリーミングか非同期 API を使います |
「一時的に利用できない」を意味する 404 があります
Model "X" is not supported by any configured account in this group が返った場合、まず同じキーで GET /v1/models を呼んでください。一覧にあるなら一時的に利用できないだけで、502 / 503 と同じ扱いです。一覧にない場合に限り、そのプランに当該モデルが含まれていません。
再試行のルール
- そのまま再試行しない: 400、402、403、404、413、422。リクエスト、設定、残高のいずれかを直してから送ります。
- 間隔を空けて再試行する: 429、502、503、504、およびストリーム中断。2 秒、5 秒、15 秒の順で最大 3 回を目安にします。
- 429 には再試行の手がかりが付きます:
Retry-After（秒）とRetry-After-Ms（ミリ秒）。ある場合はそれに従ってください。 - 受理済みの非同期ジョブを再送しない: 動画や非同期画像生成は送信が成功した時点でタスクが作成されます。再送すると別タスクが作られ、それぞれ課金されます。ステータスはポーリングで確認してください。
ストリーミング時の失敗
ストリーミングは出力が始まった時点で HTTP ステータスが 200 になり、その後は変わりません。以降の失敗はイベントとして通知されます。
- OpenAI プロトコル:
event: error（Responses プロトコルではresponse.failed） - Anthropic プロトコル:
event: error
読み取りループの中でエラーイベントを処理してください。受信済みの断片は再開できないため、リクエスト全体を送り直します。
問い合わせ時に必要な情報
- レスポンスヘッダー
x-request-id（すべてのレスポンスに付与され、そのリクエストを一意に特定できます） - 発生時刻（タイムゾーン付き）とモデル ID
- エラー本文全文と HTTP ステータスコード
これらを添えてお問い合わせいただければ、該当リクエストを直接追跡できます。