> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 冪等性

> idempotencyKeyで送信の重複を除きます。単発とバッチでは重複の扱いが異なります。

`idempotencyKey` は呼び出し側が任意で指定する文字列で、送信を重複排除の対象にします。同じキーで2回送信すると、
2回目は新しい作業をキューに入れず、1回目が作成したタスクに解決されます。

```json theme={null}
{
  "taskType": "GEMINI",
  "idempotencyKey": "job-42:prompt-7:gemini",
  "payload": { "prompt": "best wireless earbuds 2026" }
}
```

省略すると**重複排除は行われず**、送信のたびに新しいタスクが作られます。単発の問い合わせなら妥当な選択ですが、
cronや再試行するワーカーが2回送信しうるものには向きません。

<Tip>
  よいキーは試行ではなく作業そのものから決定的に作られます。作業単位を定める識別子を
  `"{jobId}:{promptId}:{engine}"` のように組み合わせると、再試行でも自然に同じキーが再現されます。
</Tip>

## 単発とバッチは意図的に異なります

2つのエンドポイントが異なる唯一の箇所で、つまずきやすいポイントです。

<CodeGroup>
  ```json Single — duplicate is an error theme={null}
  POST /v1/async/task
  → 409 Conflict

  {
    "success": false,
    "error": {
      "code": "RESOURCE_ALREADY_EXISTS",
      "message": "Task already exists.",
      "timestamp": "2026-07-09T04:12:00.000Z"
    }
  }
  ```

  ```json Batch — duplicate is a success theme={null}
  POST /v1/async/task/batch
  → 200 OK

  {
    "success": true,
    "summary": { "total": 1, "succeeded": 1, "failed": 0 },
    "results": [
      {
        "success": true,
        "index": 0,
        "task": { "id": "8f2c1e40-...", "status": "QUEUED", "...": "..." }
      }
    ]
  }
  ```
</CodeGroup>

単発エンドポイントは明示的な作成のセマンティクスを保ちます。タスクの作成を求めたのに既に存在するなら、
それは競合であり、呼び出し側が知るべきことです。

バッチエンドポイントは**重複を成功として吸収します**。呼び出し側は通常、再起動後にジョブ全体を再送信する
ワーカーであり、キー1つが既にキューにあるからといって500件のバッチを失敗にしては冪等キーの意味がありません。
返ってくる `results[i].task` は*既存の*タスクなので、タスクの対応付けはそのまま解決されます。

## 結果と送信を対応付ける

独立した2つのハンドルがあり、両方が必要です。

<ResponseField name="results[].index" type="integer">
  入力配列と位置で1:1に対応します。バッチのレスポンスを送信したタスクと突き合わせるのに使います。
</ResponseField>

<ResponseField name="task.idempotencyKey" type="string">
  送信した値がそのまま返ります。数分後に順不同で届き、元の配列を参照しない*Webhook*を突き合わせるのに使います。
</ResponseField>

<Note>
  `idempotencyKey` を指定しなかった場合、このフィールドは `null` として返されず、タスクオブジェクトから
  **省略**されます。内部ではタスク自身のuuidをキーとして使い、これは構造上一意なので重複排除は起きません。
</Note>

## キーの有効期間

永久保持されるタスクのキーは、完了、失敗、24時間の公開ポーリング期間を過ぎても予約されたままです。
ポーリングが404を返してもキーは解放されません。1回の送信の通信再試行には同じキーを使い、別の実行には
新しい実行キー(例: `:r1` サフィックスを追加)を使ってください。UUID形式である必要はありません。永久保持が
有効になる前にレガシー履歴へ移されたレコードは、遡ってキーを予約しません。