本文へスキップ
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": "…" }
}

Anthropic 形式には code がありません。キー検証のエラー（401、クォータの 402、アカウントの 403）は /v1/messages でも OpenAI 形式です。メッセージの言語はリクエストヘッダー Accept-Language に従い、指定がない場合は英語です。プログラムでは HTTP ステータスコードと code で判定し、メッセージ本文で分岐しないでください。

ステータスコード

コード主な原因再試行対処
401キー未指定、コピー漏れ、無効化済み、期限切れ不可コンソールの「API キー」から再取得するか、新規作成します
402残高やキー・メンバー・部門のクォータ切れ、動画送信時の残高引当不足チャージ後に可GET /v1/usage でこのキーの残り利用可能額を確認し、チャージまたはクォータを調整します。ループでの再試行は避けてください
403アカウントやメンバーの無効化、グループの権限・紐付けなし、機能が未開通不可管理者に連絡するか、対応するグループのキーを使います
404モデルがこのキーのグループに無い、パスが対象外、グループが提供終了不可このキーで GET /v1/models を呼び ID を確認します。パスはBase URL とプロトコルを参照。提供終了した ID と後継モデルはモデル変更履歴を参照
413リクエストボディが 60 MB 超不可素材を圧縮するか、モデルが対応していれば URL を渡します
429アカウントまたはキーの同時実行上限、あるいはサービスが混雑中可Retry-After に従って再試行し、同時実行数を下げます
499コンソールの使用記録のみ: クライアントが先に切断しており、受け取りません—長い出力はストリーミングにし、クライアントの読み取りタイムアウトを延ばします
502 / 503サービスが一時的に利用できず、自動リトライでも復旧せず可間隔を空けて再試行するか、同系列の別モデルに切り替えます
504処理がタイムアウト可間隔を空けて再試行します。長時間の処理はストリーミングか非同期 API を使います

エラーコード一覧

# OpenAI 形式の code です。モデル自身の 400 には独自の code が付くことがあります。
状態  code                          意味                                       再試行
401   missing_api_key               キー未指定                                 不可
      invalid_api_key               キーが無効または削除済み                   不可
      api_key_expired               キーの期限切れ                             不可
402   insufficient_quota            残高 / キー / メンバー / 部門クォータ切れ  チャージ後
      insufficient_balance          動画: 残高が処理中の引当 + 今回の見積もりに不足   タスク終了またはチャージ後
403   account_disabled              アカウント無効化                           不可
      member_disabled               メンバーアカウント無効化                   不可
      member_group_forbidden        メンバーがこのキーのグループを利用不可     不可
      api_key_misconfigured         キーがグループ未設定                       不可
      image_generation_disabled     グループで画像生成が未開通                 不可
      middleware_denied             ゲートウェイのポリシーで拒否               不可
404   model_not_found               グループがモデル非対応                     不可
      model_not_served              グループがモデルを提供していない           不可
      group_offline                 グループが提供終了                         不可
      route_not_found               このキーでは非対応のパス                   不可
400   invalid_request               ボディ読取不可 / JSON オブジェクトでない / model なし / messages が空   不可
413   request_too_large             ボディが 60 MB 超                          不可
429   user_concurrency_limit        アカウント同時実行上限（Retry-After: 1）   可
      apikey_concurrency_limit      キー同時実行上限（Retry-After: 1）         可
      all_routes_rate_limited       サービス混雑                               可
      upstream_rate_limit           サービス混雑                               可
502   upstream_error                サービス一時利用不可                       可
503   no_available_route            サービス混雑                               可
      no_available_account          サービス混雑（セッション再開の例外は下記） 可*
      all_routes_failed             サービス一時利用不可                       可
      plugin_unavailable            サービス一時利用不可                       可
      service_unavailable           認証サービス一時利用不可                   可
504   upstream_timeout              タイムアウト                               可

再試行のルール

  • そのまま再試行しない: 400、402、403、404、413、422。リクエスト、設定、残高を直してから送ります。404 は確定結果です: 一時的な利用不可は 429 / 5xx で、404 にはなりません。
  • 間隔を空けて再試行する: 429、502、503、504、およびストリーム中断。2 秒、5 秒、15 秒の順で最大 3 回を目安にします。例外: セッションが「can no longer be resumed」という 503 は、previous_response_id を外して新しい会話を始めます。
  • 429 の再試行ヒント: Retry-After（秒）と Retry-After-Ms（ミリ秒）があれば従います。
  • 受理済みの非同期ジョブを再送しない: 再送のたびに別タスクとして課金されます。ポーリングしてください。

ストリーミング時の失敗

ストリーミングは出力が始まった時点で HTTP ステータスが 200 になり、その後は変わりません。以降の失敗はイベントとして通知されます。

Chat Completions   data: {"error": {…}}      （event: 行なし）
Responses          event: response.failed    （response.error.code: rate_limit_exceeded / server_error / invalid_prompt）
Anthropic          event: error

読み取りループ内でエラーイベントを処理し、リクエスト全体を送り直します（断片の再開は不可）。

非同期タスクの失敗

送信時の拒否は通常の 4xx で、タスクは作られません。受理後の失敗はポーリングが 200 のまま status: "failed" を返し、理由は error.message（画像タスクは error 文字列）にあります。code はなく(Kling と Midjourney のタスクは例外で、input_sensitive・invalid_request・generation_failed などの安定した error.code を返します)、課金されません。審査やパラメータの失敗はそのまま再送しないでください。コンソールの「使用記録」に分類と対処が出ます:

審査          input_sensitive, safety_rejected …                        プロンプトや素材を修正
パラメータ    prompt_required, upstream_invalid_request, reference_* …  値を修正
タイムアウト  系列ごとの上限は「同時実行数、タイムアウト、課金」        再送信
中断          task_interrupted                                          再送信

問い合わせ時に必要な情報

  • レスポンスヘッダー x-request-id（全レスポンスに付き、リクエストを一意に特定します）
  • 発生時刻（タイムゾーン付き）とモデル ID
  • エラー本文全文と HTTP ステータスコード

サービス側の障害はコンソールに原文が出ないため、x-request-id で追跡します。これらを添えてお問い合わせください。

次のステップ

このページの内容

エラーレスポンスの構造ステータスコードエラーコード一覧再試行のルールストリーミング時の失敗非同期タスクの失敗問い合わせ時に必要な情報次のステップ