直感的な例#

• 部屋の電気のスイッチを「ON 状態にする」操作 → 何回押してON にしても、最終状態は同じ。冪等。
• 「もう一つカートに足す」操作 → 押すたびに増える。冪等ではない。

HTTPメソッドに置き換えると、GET、PUT、DELETE は仕様上冪等であることが期待されていて、POST は基本的に冪等ではありません。

なぜ重要か#

クライアントとサーバーの間には常にネットワークがあって、

• レスポンスが返ってこなかった
• タイムアウトした
• 5xx が返った

といったケースで、クライアントは「成功したのか失敗したのか分からない」状態になります。冪等であれば、迷わず リトライ していい。冪等でないと、「二重決済」「重複登録」のような事故が発生します。

実装パターン：Idempotency-Key#

決済APIなど、本質的に非冪等な処理を冪等に振る舞わせる定番が、Idempotency-Key ヘッダーです。

1. クライアントが、リクエストごとにユニークなキー（UUIDなど）を生成し、ヘッダーに添える。
2. サーバーは、そのキーで処理結果を記録する（成功／失敗／処理中）。
3. 同じキーで再度来たら、新しく処理せず、記録してある結果を返す。

Stripe や多くの決済プロバイダがこの方式を採用しています。

実装上の注意#

• キーの有効期間：永遠に持つわけにはいかないので、24時間〜数日程度で破棄するのが一般的。
• 競合：同じキーで同時に複数リクエストが来たときに備えて、DB側でロックや一意制約を使う。
• 冪等＝安全、ではない：冪等性は「同じ結果になる」ことを保証するだけ。副作用そのもの（メール送信など）の重複は別に考える必要がある。

「リトライしていいか」を設計の早い段階で決めておくと、後から運用が楽になります。