運営 · 2026-09-01 · HippoAPI Documentation Team

エラーと再試行

API エラーを分類し、有用な証拠をキャプチャし、繰り返しても安全な一時的なリクエストのみを再試行します。

エラー応答形状

2xx 以外の応答では、人間が判読できるメッセージを含むエラー オブジェクトが使用され、タイプ、コード、またはリクエスト ID が含まれる場合があります。 HTTP ステータスを最初の分類信号として扱い、リクエスト ID が存在する場合はそれを保存します。

{
  "error": {
    "message": "Error description (request id: ...)",
    "type": "new_api_error",
    "code": ""
  }
}

ステータスコードとアクション

Status意味アプリケーションアクション
400無効なリクエスト、モデル、フィールド、またはサポートされていないパラメータです。リクエストを修正します。同じ本体を変更せずに再試行しないでください。
401API キーが欠落している、形式が間違っている、有効期限が切れている、無効になっている、または無効です。キーを修正または回転します。自動的に再試行しません。
403アカウント、キー、IP、グループ、またはモデルは許可されていません。アクセス制御とモデルの可用性を確認します。
402残高または割り当てが不足しています。さらにリクエストを送信する前に、ウォレットとキーの割り当てを確認してください。
404エンドポイントまたはモデル リソースが見つかりません。ベース URL、エンドポイント パス、および正確なモデル識別子を確認してください。
429現在のリクエストレートまたは同時実行性が高すぎます。ジッターを減らして同時実行性を減らします。
5xxプラットフォームまたは上流プロバイダーの障害。厳格な試行制限を設けて安全なリクエストを再試行します。リクエストIDを保存します。

有界指数バックオフを使用する

一時的な可能性が高いエラー (接続失敗、HTTP 429、および選択された 5xx 応答) のみを再試行します。ランダムなジッターを追加して、多くのワーカーが同時に再試行しないようにします。最大試行回数と全体の期限の両方を設定します。

const delaysMs = [500, 1000, 2000]

for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
  try {
    return await callHippoAPI()
  } catch (error) {
    const status = error?.status
    const retryable = status === 429 || (status >= 500 && status < 600)
    if (!retryable || attempt === delaysMs.length) throw error
    const jitter = Math.floor(Math.random() * 250)
    await new Promise((resolve) => setTimeout(resolve, delaysMs[attempt] + jitter))
  }
}

秘密を記録せずに証拠を記録する

Authorization ヘッダー、完全な API キー、または個人データ、機密データ、規制データを含む完全なプロンプトをログに記録しないでください。エラーを可観測性ツールに転送する前に編集します。

  • UTC タイムスタンプとアプリケーション トレース ID。
  • HippoAPI リクエスト ID (存在する場合)。
  • HTTP メソッドとエンドポイントのパス。
  • モデル識別子、ステータス コード、期間、および再試行。
  • 編集されたエラーの概要。

サポートに問い合わせる前に

最小の安全なリクエストで問題を再現し、モデルが GET /v1/models に表示されることを確認し、使用状況ログを確認します。次に、タイムスタンプ、エンドポイント、モデル、HTTP ステータス、リクエスト ID、および編集されたリクエストの概要を [email protected] に提供します。

API キーは含めないでください。すでに共有または公開している場合は、調査を続行する前にそれを取り消してください。