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

# 冪等性とリトライ

> リクエストを安全にリトライし、重複ラベル作成を防止する方法

<Note>
  このページは英語から翻訳されています。[英語版](/introduction)が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。
</Note>

# 冪等性とリトライ

配送ラベルには実際のコストと物流への影響があります。重複ラベルは運用上の混乱、配送コストの無駄、在庫追跡のエラーを引き起こします。Flex Forward APIには、これを防止する冪等性が組み込まれています。

## 冪等性の仕組み

`POST /labels` エンドポイントは `idempotencyKey` フィールドを使用して、各ラベル作成リクエストが一度だけ処理されることを保証します。

**最初のリクエスト** — APIがラベルを作成し、HTTP 201を返します：

```bash theme={null}
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "N-2026-05-27-TEST-03",
    "courier": "yunexpress",
    ...
  }'
```

```json 201 Created theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
```

**リプレイされたリクエスト** — 同じ `idempotencyKey` は新しいラベルを作成せずに、HTTP 200で元の結果を返します：

```json 200 OK（冪等リプレイ） theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
```

冪等性キーはAPIアカウントにスコープされています。異なるアカウントが同じキーを使用しても衝突しません。

## 冪等性キーの選択

キーは意図されたラベル作成を一意に識別する必要があります。良いパターン：

| パターン  | 例                                      | ユースケース     |
| ----- | -------------------------------------- | ---------- |
| 注文ID  | `N-2026-05-27-TEST-03`                 | 注文ごとに1ラベル  |
| 注文+連番 | `N-2026-05-27-TEST-03-1`               | 注文ごとに複数ラベル |
| UUID  | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | 汎用         |

<Warning>
  同じ論理リクエストをリトライする際に、新しい `idempotencyKey` を生成しないでください。APIが重複を検出できるよう、元のキーを再利用してください。
</Warning>

<Note>
  400バリデーションエラーの後、ラベルが作成されていないため同じ `idempotencyKey` を再利用できます。リクエストを修正して同じキーでリトライしてください。
</Note>

## リトライ戦略

一時的な障害（HTTP 500、502、またはネットワークタイムアウト）の場合は、指数バックオフでリトライしてください：

<Steps>
  <Step title="リクエストタイムアウトを設定">
    HTTPリクエストに適切なタイムアウト（例：30秒）を使用してください。
  </Step>

  <Step title="障害発生時、リトライまで待機">
    指数バックオフを使用：1秒、2秒、4秒、8秒。
  </Step>

  <Step title="同じ冪等性キーを再利用">
    常に元のリクエストと同じ `idempotencyKey` でリトライしてください。元のリクエストが成功したがレスポンスが失われた場合でも、重複ラベルが作成されないことが保証されます。
  </Step>

  <Step title="リトライ回数を制限">
    3〜5回のリトライで停止してください。それでも失敗する場合は、エラーを記録して調査にエスカレーションしてください。
  </Step>
</Steps>

```
試行 1: POST /labels → タイムアウト
  1秒待機
試行 2: POST /labels → 502
  2秒待機
試行 3: POST /labels → 200（冪等リプレイ — ラベルは試行1で作成されていた）
```

## エンドポイント別の冪等性

| エンドポイント              | 冪等 | メカニズム                                 |
| -------------------- | -- | ------------------------------------- |
| `POST /labels`       | はい | `idempotencyKey` フィールド — すべてのリクエストで必須 |
| `GET /labels/{id}`   | はい | 読み取り専用 — 自然に冪等                        |
| `GET /tracking/{id}` | はい | 読み取り専用 — 自然に冪等                        |

## 障害シナリオ

<AccordionGroup>
  <Accordion title="レスポンス受信前のネットワークタイムアウト">
    ラベルが作成されたかどうか不明です。同じ `idempotencyKey` でリトライしてください。ラベルが作成されていた場合、APIはHTTP 200で元の結果を返します。作成されていない場合、ラベルを作成してHTTP 201を返します。
  </Accordion>

  <Accordion title="HTTP 500 内部サーバーエラー">
    一時的なサーバーエラーです。同じ `idempotencyKey` でバックオフを使用してリトライしてください。
  </Accordion>

  <Accordion title="HTTP 502 バッドゲートウェイ（配送業者エラー）">
    配送業者サービスがエラーを返しました。ラベルは `status: failed` で保存されています。リトライする前にエラーメッセージを確認してください — 一部の配送業者エラーはリクエストの変更が必要です（無効な住所など）。一時的な配送業者の問題の場合は、同じ `idempotencyKey` でリトライしてください。
  </Accordion>

  <Accordion title="HTTP 400 バリデーションエラー">
    リクエストが無効です。リクエストを修正せずにリトライしないでください。ラベルが作成されていないため、リクエストボディを修正した後に同じ `idempotencyKey` を再利用できます。
  </Accordion>
</AccordionGroup>