---
title: 冪等なリクエスト
description: 受付結果が分からないとき、同じ生成を重複させずに再試行します。
canonical_url: https://orchestor.io/docs/creative/concepts/idempotency
markdown_url: https://orchestor.io/docs/creative/concepts/idempotency.md
contentType: guide
---

# 冪等なリクエスト

生成の送信には `Idempotency-Key` を付けます。通信切断やタイムアウトで受付結果が分からないときも、一つの生成には同じキーを使います。

```bash
export IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST https://api.orchestor.io/v1/creative/image-router/generate \
  --header "Authorization: Bearer $ORCHESTOR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"model":"gpt-image-2","prompt":"朝の光が差し込む湖","mode":"async"}'
```

応答を受け取れなかった場合は、同じ入力とキーで再送します。同じジョブが返り、`idempotency_hit` で再送だったかを確認できます。

## キーのルール

- 1〜255 文字の印字可能な ASCII 文字を使います。UUID を使用できます。
- 生成の前にキーを作り、入力と一緒に保存します。
- 同じ生成の再試行ではキーと入力を変えません。
- 意図的に別の生成を依頼する場合は、入力が同じでも新しいキーを作ります。
- 受付済みのジョブを待つときは、再送せず状態を取得します。

## パラメーターの不一致

同じキーで異なる入力を送ると `409` になります。エラー本文の `error.code` と `error.message` を確認してください。

```json
{
  "error": {
    "code": "idempotency_conflict",
    "message": "同じ冪等性キーで入力が変わっています。別の生成なら新しいキーを使用してください。",
    "request_id": "req_00000000000000000000000000000000",
    "category": "validation",
    "stage": "validation",
    "retryable": false,
    "retry_after_seconds": null,
    "public_reason": "idempotency_conflict",
    "next_action": "fix_input"
  }
}
```

自動的に新しいキーへ置き換えず、入力の変更が意図した新しい生成なのか、クライアントの不具合なのかを確認します。

## 受付結果が分からない場合の再試行

1. 送信前にキーを作成します。
2. アプリケーションの処理記録にキーと入力を保存します。
3. 通信切断やタイムアウトでは、同じ入力とキーで再送します。
4. 返されたジョブ ID を保存し、`status_url` で現在の状態を確認します。

`queue_full`、`provider_capacity_exceeded`、`provider_rate_limited`、再試行可能な `provider_submission_failed` でも同じキーを使います。残高不足やキーの利用上限など確定した拒否は、原因を解消してから新しいキーで送ります。[エラーと再試行](https://orchestor.io/docs/creative/errors.md)も確認してください。

---

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