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 を記録し、問い合わせに添えてください。