---
title: エラーと再試行
description: 受付時の HTTP エラーと、受付後に失敗したジョブを区別します。
canonical_url: https://orchestor.io/docs/creative/errors
markdown_url: https://orchestor.io/docs/creative/errors.md
contentType: guide
---

# エラーと再試行

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

## 同期的なエラー

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

```json
{
  "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` になる場合があります。ジョブ取得応答の抜粋です。

```json
{
  "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` を守り、指数バックオフとランダムな待ち時間を使います。
- 再試行回数と総待機時間に上限を設けます。
- 生成の送信には[冪等性キー](https://orchestor.io/docs/creative/concepts/idempotency.md)を付けます。
- 受付結果が不明なら同じ入力とキーで再送します。既存ジョブの状態確認に新しい生成を使わないでください。

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

---

[Documentation index](https://orchestor.io/docs/llms.txt)
