LASSIC Media らしくメディア
冪等性(Idempotency)設計を外注で進める
LASSIC IT事業部｜元請（プライムベンダー）としてシステム保守・運用を受託
この記事のポイント
- 通信のタイムアウトやリトライによって同じリクエストが複数回サーバーに届くことは、ネットワークを介したAPI設計では避けられない現実です
- 冪等性(Idempotency)は、同じ操作を複数回実行しても結果が変わらない性質を指し、決済や在庫更新のような重要な処理では設計上の対応が欠かせません
- 冪等キーの設計・保持期間・並行リクエストの扱いには技術的な論点が多く、委託範囲を整理したうえで外注先に相談する進め方が現実的です
目次
冪等性(Idempotency)とは何か、なぜAPI設計で問題になるのか
冪等性(Idempotency)とは、同じ操作を1回実行した場合と複数回実行した場合とで、サーバー側の結果が変わらない性質を指します。MDN(Mozilla Developer Network)は「HTTPメソッドが冪等であるとは、単一のリクエストを行った場合にサーバーに与える意図された効果が、同一のリクエストを複数回行った場合の効果と同じであることをいう」と定義しています*1。
APIの通信は、クライアントとサーバーの間にネットワークが介在するため、リクエストが一度だけ届く保証はありません。リクエスト送信後にタイムアウトが発生した場合、クライアントから見るとサーバーで処理が成功したのか失敗したのかを区別できず、処理漏れを避けるなら再送するほかありません。
このとき、サーバー側の処理がPOSTによる決済実行や注文登録のように非冪等であると、再送のたびに二重決済や二重登録が発生するおそれがあります。冪等性は、こうしたリトライを前提とした設計において、重複実行を防ぐための中心的な考え方です。
リトライとat-least-once配信 — 重複が発生する仕組み
分散システムにおけるメッセージ配信の保証には、大きく分けて「高々1回(at-most-once)」「少なくとも1回(at-least-once)」「正確に1回(exactly-once)」の3種類があります。ネットワーク上でメッセージの到達を確認する仕組みを持つ多くのシステムは、メッセージの欠落を避けるためにat-least-once配信を採用します。
at-least-once配信は、送信側が受信側からの確認応答(ACK)を受け取れなかった場合に再送する方式です。確認応答自体がネットワーク障害で失われた場合、受信側では処理が成功していても送信側は失敗と判断し、再送が発生します。この結果、受信側では同じ処理が複数回実行される可能性が残ります。
exactly-once配信、つまりメッセージが重複も欠落もなく正確に1回だけ処理される保証は、分散システムの理論上、ネットワークの遅延や障害を完全に排除できない限り実現が困難とされています。実務での現実的な対応は、配信自体はat-least-onceを許容したうえで、受信側の処理を冪等にすることで「重複して届いても結果は1回分と同じ」状態を作ることです。
決済処理を例にすると、クライアントがタイムアウト後に同じ決済リクエストを再送しても、サーバー側が冪等性を確保していれば、口座からの引き落としは1回しか発生しません。逆に冪等性の対応がなければ、ネットワークの不確実性がそのまま二重決済のリスクに直結します。
HTTPメソッドの冪等性 — GET/PUT/DELETEとPOSTの違い
HTTPの仕様上、メソッドごとに冪等性の有無があらかじめ定められています。MDNの整理によると、GET・PUT・DELETE・HEAD・OPTIONS・TRACEは冪等なメソッドに分類され、POSTとPATCHは冪等性が保証されないメソッドに分類されます*1。
| HTTPメソッド | 冪等性 | 理由 |
|---|---|---|
| GET | 冪等 | リソースの取得のみを行い、サーバーの状態を変更しないためです。 |
| PUT | 冪等 | 指定した内容でリソース全体を置き換える操作のため、何度実行しても最終状態は同じです。 |
| DELETE | 冪等 | 初回は削除に成功し、以降は対象が存在しないため結果として「削除された状態」が保たれます。 |
| POST | 非冪等 | 新規リソースの作成を伴う場合、実行のたびに新しいリソースが追加されます。 |
| PATCH | 非冪等(場合による) | 差分適用の内容次第で、複数回の実行が異なる結果を生む可能性があります。 |
MDNは、冪等なメソッドであってもサーバー側でログの記録などの副作用が発生する場合があると注記しています*1。冪等性が保証するのは、あくまでクライアントの意図した効果がリクエストの回数によって変わらないという点であり、サーバー内部の全ての処理が完全に無変化になることまでは意味しません。
決済実行や注文登録のようなAPIは、性質上POSTで実装されることが一般的です。POST自体は非冪等なメソッドであるため、リトライへの耐性をAPI設計側で追加する必要があります。この追加設計の代表的な手法が、次に説明する冪等キーです。
冪等キー(Idempotency-Key)による設計手法
冪等キーは、非冪等なPOSTやPATCHのようなHTTPメソッドを、リトライに強い(耐障害性のある)操作にするための設計手法です。IETF(Internet Engineering Task Force)のインターネットドラフトでは、「HTTPのIdempotency-Keyリクエストヘッダーフィールドは、POSTやPATCHのような非冪等なHTTPメソッドを耐障害性にするために利用できる」と説明されています*2。なお、このドラフトは2025年10月に公開された文書で、2026年4月に有効期限が切れており、RFC(標準仕様書)として正式に確定した状態ではありません*2。
基本的な仕組みは、クライアントがリクエストごとに一意なキーを生成し、Idempotency-Keyというヘッダーに設定してサーバーに送信するというものです。サーバー側は、そのキーで最初に処理したリクエストの結果(ステータスコードとレスポンス本体)を記録しておきます。同じキーを持つリクエストが再び届いた場合、サーバーは処理を再実行せず、記録しておいた最初の結果をそのまま返します。
決済代行サービスのStripeは、このパターンを実装で公開している一次情報の例です。Stripeの公式ドキュメントによると、冪等キーを付与したリクエストが最初に処理された際、APIはそのステータスコードとレスポンス本体を保存し、同じキーで後続のリクエストを受け取った場合は保存済みの結果を返すとされています*3。この保存は成功したリクエストだけでなく、サーバーエラーが発生した場合の結果も対象になると説明されています*3。
冪等キーの仕組みはGETやDELETEのようなもともと冪等なメソッドには不要です。Stripeのドキュメントも、冪等キーの対象を性質上非冪等になり得るリクエストに限定しています*3。設計としては、決済実行・注文登録・在庫引当のようなPOST系のAPIに冪等キーを組み込み、参照系のAPIには適用しないという切り分けが基本になります。
導入の論点 — 保持期間・並行リクエスト・適用範囲
冪等キーの設計を実装に落とし込む際には、いくつかの技術的な論点を事前に整理しておく必要があります。第一の論点は、キーと処理結果をどの程度の期間保持するかです。Stripeのドキュメントでは、冪等キーは少なくとも24時間保持され、24時間が経過すると新しいリクエストとして扱われる仕様になっています*3。保持期間を長くするほど重複防止の効果は高まりますが、保存領域や検索性能とのトレードオフが生じます。
第二の論点は、同じ冪等キーを持つリクエストが並行して(ほぼ同時に)届いた場合の扱いです。Stripeのドキュメントは、別のリクエストが同じキーで処理中である場合、その並行リクエストについては冪等性の結果を保存しない仕様になっていると説明しています*3。これは、処理中のリクエストの結果が確定する前に別のリクエストが同じキーを検出してしまうと、誤った内容を返しかねないためです。実装側では、同一キーに対する排他制御(ロック)の仕組みが必要になります。
第三の論点は、どの処理に冪等性の対応を適用するかという範囲の見極めです。決済・注文登録・在庫引当のように、重複実行が金銭的損失や在庫不整合に直結する処理は、優先的に冪等性を確保すべき対象です。一方、参照系のAPIや、重複実行の影響が軽微な処理まで一律に冪等キーの仕組みを組み込むと、実装・運用コストが増える割に効果が限定的になる場合があります。
第四の論点は、リクエストパラメータの検証です。Stripeのドキュメントによると、同じ冪等キーで異なるパラメータを持つリクエストが送られた場合はエラーになる仕様です*3。これは、同一キーであってもリクエスト内容が異なる場合に誤って古い結果を返してしまう事態を防ぐための設計です。自社で冪等キーの仕組みを実装する場合も、キーとリクエスト内容の組み合わせを検証するロジックが必要になります。
外注の委託範囲と発注準備
冪等性の設計を外注する場合、委託範囲を事前に整理しておくことが発注後の手戻りを防ぎます。委託範囲として想定される作業は、大きく分けて対象処理の洗い出し・設計・実装検証の3段階です。
- 既存APIのうち決済・注文登録・在庫引当など、重複実行時の影響が大きい非冪等な処理の棚卸しと優先順位付け
- 冪等キーの生成方法(クライアント側かサーバー側か)・保存先・保持期間・並行リクエストの排他制御方式の設計
- タイムアウトやネットワーク断を模した重複リクエストのテストケース作成と、実装後の動作検証
発注前には、対象となるAPIの一覧・現在のリトライ処理の実装状況・決済や在庫のような重要処理がどのメソッドで実装されているかを整理しておくと、外注先からの見積もり精度が高まります。冪等性の対応は一部のAPIから段階的に組み込むことができるため、まず重複リスクが大きい決済系のAPIから着手し、対応範囲を広げる進め方も選択肢になります。
冪等キーの保持期間設計・並行リクエストの排他制御・重複排除テーブルの設計といった実装には専門知識が必要です。設計を誤ると、重複防止の仕組み自体が正しく機能せず二重決済を防げなかったり、逆に正当な別注文まで誤ってブロックしてしまったりするおそれがあるため、実装経験を持つ外部パートナーへの相談が有効な選択肢になります。
まとめ：冪等性設計で押さえる3つの判断軸
本稿では冪等性(Idempotency)の仕組みと設計上の論点を整理しました。要点を3つに集約すると次の通りです。第一に、ネットワークのタイムアウトやat-least-once配信によってリクエストが重複することは避けられず、非冪等な処理では二重決済や二重登録につながります。第二に、GET・PUT・DELETEは仕様上冪等ですが、決済や注文登録に使われるPOSTは非冪等であり、冪等キーによる追加設計が必要です。第三に、キーの保持期間・並行リクエストの排他制御・適用範囲の見極めには技術的な論点が多く、重要処理から優先的に外部パートナーへ相談する進め方が現実的です。
よくある質問
冪等性とキャッシュは同じ概念ですか。
異なる概念です。冪等性は「同じ操作を複数回実行しても結果が変わらない」という性質を指し、キャッシュは「一度取得した結果を再利用する」仕組みです*1。冪等キーはリクエストの重複実行を防ぐための識別子であり、レスポンスを高速化するためのキャッシュとは目的が異なります。
PATCHメソッドは冪等ですか、非冪等ですか。
PATCHは冪等性が保証されないメソッドに分類されます*1。差分を適用する内容次第で結果が変わるためです。ただし実装によっては冪等な差分適用(値を絶対値で指定するなど)にすることも可能で、メソッドの種類だけで自動的に決まるものではありません。
exactly-once配信を実現すれば冪等性の設計は不要になりますか。
実務上は不要になりません。メッセージが重複も欠落もなく正確に1回だけ処理される保証は、ネットワークの遅延や障害を完全に排除できない限り実現が困難とされており、多くの分散システムはメッセージの欠落を避けるためat-least-once配信を採用します。そのため受信側の処理を冪等にする設計が現実的な対応になります。
冪等キーはどのくらいの期間保持すればよいですか。
明確な業界基準はありませんが、決済代行サービスのStripeでは冪等キーを少なくとも24時間保持し、24時間経過後は新しいリクエストとして扱う仕様を採用しています*3。保持期間は保存領域とのトレードオフになるため、対象処理のリトライ想定時間に応じて設計する必要があります。
同じ冪等キーで異なる内容のリクエストが届いたらどうなりますか。
Stripeの仕様では、同じ冪等キーで元のリクエストとは異なるパラメータを持つリクエストが送られた場合、エラーとして扱われます*3。これは、同一キーを異なる内容のリクエストに誤って再利用してしまうことを防ぐための検証です。自社で実装する場合も同様の検証ロジックを組み込む必要があります。
著者：テレリモ総研編集部 鈴木 亮佑
ご不明な点はお問い合わせフォームからもご連絡いただけます。
- *1 出典：MDN Web Docs「Idempotent」https://developer.mozilla.org/en-US/docs/Glossary/Idempotent（参照2026年）
- *2 出典：IETF（Internet Engineering Task Force）インターネットドラフト「The Idempotency-Key HTTP Header Field」https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header（2025年10月公開・2026年4月失効のInternet-Draft）
- *3 出典：Stripe「Idempotent requests」https://docs.stripe.com/api/idempotent_requests（参照2026年）
