# 冪等性 — Idempotency-Keyヘッダーで安全にリトライする

> Idempotency-Keyヘッダーを使用すると、ドキュメントのアップロード、バッチ処理、bboxトリガーを安全にリトライでき、同じ操作を二重に実行したり、その料金を支払ったりすることを防げます。

ネットワーク呼び出しは失敗したりタイムアウトしたりします。クレジットを消費したりリソースを作成するリクエストでそれが発生した場合、単純にリトライするとクレジットが二重に消費される可能性があります。`Idempotency-Key`ヘッダーはこの問題を解決します。リトライ時に同じキーを送信すると、元の呼び出しとまったく同じレスポンスが返され、操作が再実行されることはありません。

## 仕組み

対応しているリクエストに、クライアント側で生成した一意の文字列（UUIDが適切です）を値とする`Idempotency-Key`ヘッダーを追加します。

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e9a2c-9b41-4e6a-8c3d-2f1a5b6c7d8e" \
  -d '{"fields": [{"name": "invoice_number"}, {"name": "total_amount"}]}'
```

キーは**24時間**、`（あなたのアカウント、キー値、エンドポイント）`ごとに保存されます。その期間内にまったく同じリクエスト（同じエンドポイント、同じキー）が再度届いた場合、元のレスポンス（同じステータスコード、同じボディ）が再送され、操作自体は二度目は実行されません。つまり、同じキーでリトライされた`process`呼び出しはクレジットを二重に消費せず、同じキーでリトライされた`documents`アップロードは二つ目のドキュメントを作成しません。

`Idempotency-Key`ヘッダーがないリクエストは、これまでとまったく同じように動作します。何も保存されず、再送もされません。このヘッダーは完全にオプトインです。

## 対応エンドポイント

クレジットを消費する、またはリソースを作成するエンドポイントのみが `Idempotency-Key` を受け付けます。読み取り専用の `GET` では、読み取りの繰り返しは常に安全であるため、その利点はありません。

- `POST /documents`（ドキュメント作成）
- `POST /batches/{batch_name}/process`（処理を開始し、クレジットを消費）
- `POST /documents/{document_id}/bbox`（有料のbboxアノテーションステップをトリガー）

## 異なるパラメータでのキー再利用

`Idempotency-Key` は、汎用的なラベルではなく、*まったく同じ*リクエストを再試行するためのものです。すでに使用したキーを、異なるリクエストパラメータ（異なる `batch_name`、異なるリクエストボディ）で再利用した場合、APIは古いレスポンスを黙って再生しません（異なるリクエストに対しては誤った動作になります）。また、どちらを意図しているかを推測することもありません。代わりに、400 `idempotency_key_reused` エラーを返します。リクエストが本当に異なる場合は、同じ種類の操作を対象としていても、新しいキーを生成してください。

## 例：再生されたレスポンス

以下の2回目の呼び出しは、すでに成功した呼び出しと同じキーで行われ、最初の呼び出しと同じボディとステータスコードを返します。クレジットは再度消費されません。

```json
{
  "batch_name": "260716-4K9P",
  "queued": 2,
  "quality": "fast",
  "webhook_registered": false
}
```

## 記録される内容

再生用に保存されるのは、成功した（2xx）レスポンスのみです。元の呼び出しが失敗した場合（バリデーションエラー、クレジット不足、その他2xx以外のエラー）は何も記録されず、同じキーで再試行すると、単に新しい操作として試行されます。これは意図的なものです。エラーこそ、再試行で実際に再度試行してほしい状況であり、キーが24時間後に期限切れになるまで同じ失敗が再生されることを防ぎます。

---

Source: https://imagetotable.ai/ja/developers/guides/idempotency