冪等性とは？「もう一度送っていい処理か」を決めていないAPIの弱点

冪等性とは？「もう一度送っていい処理か」を決めていないAPIの弱点

決済API（外部の決済サービスとシステムを連携させる窓口）を組み込んだあと、通信タイムアウトが起きた日に限って二重課金の問い合わせが集中する——という経験をした開発者は少なくないはずです。原因を調べると、たいていコードにバグは見つかりません。見つかるのは「タイムアウトしたリクエストを、もう一度送っていいかどうか」を誰も決めていなかったという設計上の空白です。

この空白を埋める概念が「冪等性（idempotency）」です。ただし、この言葉は実装のテクニックとして語られがちで、その手前にある業務判断の話だという点が見落とされやすくなっています。この記事では、HTTPの仕様書（RFC 9110）に基づいて冪等性の定義を確認したうえで、判断の順序を整理します。

30秒で要点

• 冪等性とは「同じリクエストを複数回送っても、サーバーへの意図された効果が1回分と同じになる」性質のこと。RFC 9110ではPUT・DELETE・安全なメソッド（GETなど）が冪等とされ、POSTは含まれない
• 冪等性が保証するのは「意図された効果」だけで、ログの記録など副作用まで冪等である必要はない
• クライアントは非冪等な操作の自動リトライをすべきでないとされる一方、実際には接続切断時にPOSTを自動再送するクライアントもあると仕様書自身が記している
• 独自ヘッダIdempotency-KeyはIETFの標準ではない（ドラフトは失効済み）。挙動はAPI提供側の実装依存

なぜ「冪等性=実装テクニック」と誤解しやすいのか

冪等性は多くの技術記事で「Idempotency-Keyヘッダを付ける」「リトライ時に同じキーを送る」といった実装手順として紹介されます。手順として学ぶと、冪等性は「サーバー側に用意された機能を呼び出す作法」のように見えてしまいます。

しかし実際には、冪等性の出発点は実装ではなく業務判断です。「この操作をもう一度実行してしまったら、何が起きるか」——決済なら二重課金、在庫引当なら二重確保、単なる設定更新なら実害なし、というように、操作ごとに再送の許容度はまったく異なります。この判断を先に済ませていないと、どれだけ丁寧にリトライ処理を実装しても、守るべきものを取り違えたまま作業を進めることになります。

RFC 9110が定義する「冪等性」

ここで見落とされやすいのが「意図された効果」という限定です。RFC 9110は同じ箇所で、冪等性という性質は「ユーザーが要求したこと」にのみ適用されるとし、サーバー側がリクエストごとに個別のログを残したり、改訂履歴を保持したりするなど、冪等でない副作用を持つこと自体は許容されると明記しています。つまり「冪等なAPI」であっても、内部ではリクエストのたびに何かが記録されているのが普通で、それは仕様違反ではありません。

確かなこと：RFC 9110の本文において、PUT・DELETE・安全なメソッドが冪等に分類されること、および冪等性がユーザーの意図した効果のみに適用される概念であることは、条文の記載から直接確認できます。

まだ確かではないこと：個々のAPI実装がこの定義どおりに冪等に作られているかどうかは、仕様書だけでは分かりません。「PUTだから冪等」と機械的に信じるのではなく、利用するAPIのドキュメントで実際の挙動を確認する必要があります。

規範と実態のあいだ——POSTの自動リトライという例外

RFC 9110は、非冪等なメソッド（POSTなど）についてクライアントが自動的にリトライすべきではない（SHOULD NOT）としており、プロキシに対しては非冪等リクエストの自動リトライを明確に禁止（MUST NOT）しています。

興味深いのは、同じ条文の中に規範とは別の記述があることです。RFC 9110は「一部のクライアントは、より危険なアプローチ（riskier approach）を取り、自動リトライが可能かどうかを推測しようとする」とし、その例として「応答の一部も受け取る前に接続が切断された場合、クライアントがPOSTリクエストを自動的にリトライすることがある」という実態を挙げています。

これは「規範としてはNGだが、現場では起きている」という隙間を仕様書自身が認めている箇所です。自社が組み込んでいるHTTPクライアントライブラリやSDKが、こうした「危険なアプローチ」を内部で採用していないかは、ドキュメントを確認しないと分かりません。リトライを禁止する設計にしていたつもりが、ライブラリの挙動によって意図せずリトライが発生している、という事故はここから生まれます。

Idempotency-Keyヘッダは「標準」ではない

決済系のAPIでよく見るIdempotency-Keyヘッダ（リクエストに一意なキーを付け、同じキーの再送を1回分の実行として扱ってもらう仕組み）は、IETFで標準化が試みられていました。しかしこのドラフト仕様（draft-ietf-httpapi-idempotency-key-header）は、2026年9月17日時点で「もはや活動していない（no longer active）」状態にあり、IESGのステータスは失効（Expired）、意図されたRFCの区分は「なし」に設定されています。

つまりIdempotency-Keyは、広く使われてはいるものの、IETFが正式に定めた標準ではありません。実際には各API提供者が独自に実装している機能であり、次のような挙動はベンダーごとに異なります。

• 同じキーをどれくらいの期間保持するか
• 同じキーで異なるリクエストボディが送られてきた場合にどう扱うか（エラーにするか、最初のリクエストを優先するか）
• 同時に同じキーでリクエストが届いた場合の挙動

「Idempotency-Keyに対応しているから安全」と考える前に、利用するAPIのドキュメントでこれらの挙動を個別に確認する必要があります。標準がない領域では、実装の詳細そのものが仕様書の代わりになります。

判断軸：実装より先に「二重実行の損害額」を見積もる

ここまでを踏まえると、冪等性への対応順序が見えてきます。技術的な実装方法を先に選ぶのではなく、「この操作を二重実行してしまった場合、業務としてどれくらいの損害になるか」を先に見積もることです。

• 損害が大きい操作（決済の実行、在庫の引当、注文の確定など）：Idempotency-Key相当の仕組みを持つAPIを優先的に選ぶ、または自社でPUT等の冪等なメソッド設計に寄せる
• 損害が小さい操作（設定値の更新など）：PUTのように定義上冪等なメソッドで十分なことが多い

この順序を逆にすると、「とりあえずIdempotency-Keyを実装した」という状態になり、肝心の「どれだけ厳密に保証すべきか」という判断が抜け落ちたままになります。

AIエージェントに業務APIの呼び出しを行わせる設計でも、この判断軸は同じです。エージェントがタイムアウトや通信エラーを検知して自動的にリトライする場合、その先にあるAPIが冪等でなければ、人間が想定していなかった頻度で二重実行が起きる可能性があります。エージェントの自律性を高めるほど、呼び出し先APIの冪等性を先に確認しておく重要性も高まります。

自分でも試せる、最小の検証

自社が外部に提供している、あるいは外部から呼び出しているAPIを1つ選び、「このエンドポイントに同じリクエストを2回送ったら、業務上どうなるか」を実際に確認してみてください。PUTやDELETEであっても、ログイン処理や通知送信などの副作用が2回分発生していないか、レスポンスだけでなく実際のデータ変化を見て確かめることが、冪等性の実態を把握する最短の方法です。

判断の土台として押さえておくこと

• 冪等性は「サーバーへの意図された効果」についての性質であり、ログ記録などの副作用まで縛るものではない
• RFC 9110はPOSTの自動リトライを推奨していない。ただし一部クライアントが接続切断時に自動リトライする実態も、同じ条文が認めている
• Idempotency-KeyはIETF標準ではなく、挙動はAPI提供側の実装依存。ドキュメントでの個別確認が必要
• 実装方法を選ぶ前に、「二重実行時の業務損害額」で対応の優先順位を決める

API設計における冪等性以外の判断軸（バージョニング、エラー設計など）も含めて自社のAPI設計を見直したい場合は、状況を整理するところから始めることができます。

より深く学ぶ

• API設計のベストプラクティス：RESTful、GraphQL、gRPCの選定基準と実践：API全体の設計判断を整理した記事

参考資料・引用元

• RFC Editor, "RFC 9110: HTTP Semantics" §9.2.2 Idempotent Methods. https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods
• IETF Datatracker, "The Idempotency-Key HTTP Header Field" (draft-ietf-httpapi-idempotency-key-header). https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/