Core concepts

エラーと再試行

エラーは、受付前の HTTP 応答と、受付後の生成処理の両方で発生します。

同期的なエラー

HTTP エラーは error オブジェクトで返ります。入力が不正な場合の例です。

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body.",
    "request_id": "req_00000000000000000000000000000000",
    "category": "validation",
    "stage": "validation",
    "retryable": false,
    "retry_after_seconds": null,
    "public_reason": "invalid_request",
    "next_action": "fix_input",
    "details": { "errors": [{ "path": "prompt", "message": "Required" }] }
  }
}

メッセージの文章ではなく、code、retryable、next_action で処理を分岐します。入力の不備は details に含まれる場合があります。

HTTP主な意味再試行
400・422入力が不正入力を修正してから。
401認証情報が不足、または無効認証情報を修正するまで停止。
402残高・利用枠の不足残高と利用枠を確認してから。
403権限が不足キーとワークスペースの権限を修正してから。
404対象が見つからないID と所属先を確認。
409入力や現在の状態と競合冪等性キーやジョブ状態を確認してから。
429送信数やキューの上限retry-after の待機後。
5xxサーバーや生成処理が利用できないretryable を確認し、バックオフ。

終端状態の失敗

受け付けたジョブも、後で failed になる場合があります。ジョブ取得応答の抜粋です。

{
  "data": {
    "job": {
      "id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
      "status": "failed",
      "error": {
        "category": "generation_timeout",
        "stage": "generation_processing",
        "retryable": true,
        "retry_after_seconds": 30,
        "public_reason": "generation_timeout",
        "next_action": "retry_later"
      }
    }
  }
}

状態取得の表記では FAILED、ジョブ本体では failed です。next_action が fix_input なら入力を修正し、retry_later なら待機を検討します。課金の確認はジョブの usage_summary と利用明細で行います。

安全な再試行

  • 状態取得の通信障害や再試行可能な 5xx は、同じジョブ ID で再試行します。
  • 認証・入力のエラーは、原因を直すまで繰り返しません。
  • retry-after または retry_after_seconds を守り、指数バックオフとランダムな待ち時間を使います。
  • 再試行回数と総待機時間に上限を設けます。
  • 生成の送信には冪等性キーを付けます。
  • 受付結果が不明なら同じ入力とキーで再送します。既存ジョブの状態確認に新しい生成を使わないでください。

HTTP の x-orchestor-request-id とエラーの request_id、生成ジョブの ID を記録し、問い合わせに添えてください。