分散 API は厄介な形で失敗します。サーバーがリクエストを処理し終えた後に接続が切れることがあります。プロバイダー側では処理が続いているのに、ゲートウェイがタイムアウトを返すこともあります。応答を受け取れなかったクライアントは呼び出しを繰り返します。キューは同じメッセージを再送することがあります。ユーザーが支払いボタンを二度クリックすることもあります。
一般的な処理であれば、繰り返しは作業の重複で済むかもしれません。しかし決済では、金銭的な影響が二重に発生しかねません。
冪等性(idempotency)は、同じ意図を何度送っても、繰り返すたびに新しい効果が生じないようにするための仕組みです。耐障害性の高い金融 API を構築するうえで最も重要な手段の一つであり、同時に最も誤解されやすいものの一つでもあります。
操作が冪等であるとはどういう意味ですか?
冪等な操作とは、繰り返し実行しても、最初の有効な実行がもたらした効果以上に結果が変わらない操作のことです。
100 レアルの請求を作成するという意図であれば、同じ識別子で同じリクエストを繰り返しても、独立した請求が二つ作られてはなりません。
繰り返しは、同じ論理的な操作として認識される必要があります。
冪等性とは、API が常にまったく同じ応答を返すことですか?
細部まで同じとは限りませんが、ビジネス上の効果は一度きりでなければなりません。
元の応答を保存して再度返すプロバイダーもあれば、作成済みのリソースを返すプロバイダーもあります。二度目の効果が起きないことだけを保証するところもあります。
正確な契約内容は API ドキュメントで確認する必要があります。
冪等キーとは何ですか?
クライアントが特定の意図を表すために渡す識別子です。
サーバーは初めてキーを受け取ったときに操作を実行し、その結果をキーに紐づけます。繰り返しが来た場合は、その意図がすでに処理済みであると認識し、再実行を避けます。
キーが表すべきなのは「このユーザー」ではなく、「この論理的な操作」です。
キーは誰が生成すべきですか?
通常は、ビジネス上の意図を把握しているシステムです。
バックエンドが決済試行を作成するなら、PSP を呼び出す前にその試行専用の一意なキーを生成できます。
大切なのは、同じ意図では同じキーを再利用し、新しい意図では別のキーを使うことです。
order_id を冪等キーとして使えますか?
場合によります。
注文ごとにその種類の操作が一つしかないのであれば、機能することもあります。
しかし一つの注文に複数の試行、売上確定、返金、変更が発生することがあります。その場合、order_id だけを使うと、別個の正当な操作まで止めてしまうおそれがあります。
キーにはコマンドに見合った粒度を持たせる必要があります。
ランダムな UUID で十分ですか?
衝突のリスクは解消できますが、意味づけの問題は解消できません。
リトライのたびに新しい UUID を生成していては、冪等性の利点が失われます。
キーは最初の呼び出しより前に意図と一緒に永続化し、再利用できるようにしておく必要があります。
キーはいつ作成すべきですか?
外部への操作を実行する前です。
PSP の応答を受け取ってからキーを保存する設計では、その間にクラッシュすると、どのキーを使ったのかアプリケーションが分からなくなる可能性があります。
先に意図とキーを永続化しておけば、復旧が容易になります。
冪等性と重複排除は同じものですか?
関連はしていますが、同じではありません。
重複排除は、繰り返し届いたイベントを見分けて、複数回処理しないようにすることです。
冪等性は、操作を繰り返しても追加の効果が生じないことを保証するものです。
event_id で重複排除を行っていても、外部呼び出しには別途冪等性が必要になることがあります。
exactly-once 配信はどうでしょうか?
実際のところ、分散システムがエンドツーエンドで物理的に厳密に一度だけの配信に頼れることはまれです。
キューやネットワークは、再送を伴う at-least-once 配信を優先する傾向があります。
だからこそ、冪等なコンシューマーが重要になります。
目指すのは、メッセージが何度届いてもビジネス上の効果を一度だけにすることです。
HTTP の GET はもともと冪等ですか?
HTTP のセマンティクスでは、GET はビジネス上の大きな効果を伴わない読み取りであるべきとされています。
しかし、設計の悪い API はこのルールを破ることがあります。
決済における冪等性は、主に作成、売上確定、キャンセル、返金といったコマンドに関わる問題です。
PUT は冪等ですか?
既知のリソースの状態を置き換えたり設定したりする場合、PUT の HTTP セマンティクスは冪等です。
それでも、実際の挙動は実装次第です。
HTTP メソッドだけを根拠に、金銭面の安全性を前提にしてはいけません。
POST を冪等にすることはできますか?
できます。
多くの決済 API は、冪等キー付きの POST を使って、作成やコマンドを安全に繰り返せるようにしています。
メソッドだけでは保証は決まりません。
サーバーはパラメーターを比較すべきですか?
理想的には比較すべきです。
同じキーが異なる金額やペイロードで届いた場合、クライアントにバグがある可能性が高いでしょう。
パラメーターが最初のリクエストと一致しない場合、キーの再利用を拒否する API もあります。
これにより、キーが異なる意図の汎用的な識別子になってしまうのを防げます。
キーはどのくらいの期間記憶しておくべきですか?
プロバイダーの契約と自社システム次第です。
決められた期間だけ結果を保持するサービスもあります。期間を過ぎると、キーの再利用が新しい操作として扱われることがあります。
アプリケーションはこの期間を把握し、恒久的な保証が存在しないのであれば、それに頼ってはいけません。
ローカルの冪等性は PSP より長く保持すべきですか?
良い戦略になり得ます。
プロバイダーが一定期間後にキーを忘れても、自社システムは意図を保持し、危険な遅れたリトライを防げます。
内部ルールが外部の保持期間に縛られる必要はありません。
タイムアウトが起きたらどうなりますか?
タイムアウトは典型的なケースです。
アプリケーションはリクエストを送ったものの、PSP が処理したかどうか分かりません。新しいキーを生成するのではなく、契約が許す範囲で、同じキーを使って同じ意図を繰り返すべきです。
そうすれば、最初の呼び出しがすでに効果を生んでいた場合に、サーバーが繰り返しだと認識できます。
冪等性で結果不明の状態はなくなりますか?
必ずしもそうではありません。
重複のリスクは下がりますが、最終結果を知るためにリソースを照会する必要が残る場合があります。
冪等キーは安全に繰り返すための仕組みであって、ステートマシンの代わりではありません。
冪等性で異なる PSP 間の二重請求を防げますか?
自動的には防げません。
ある PSP のキーは、通常、別の PSP にとっては何の意味も持ちません。
PSP A でタイムアウトを受けて PSP B に新しい試行を送ると、効果が二つ生じる可能性があります。
プラットフォームは、決済と試行の両方のレベルでこれを制御する必要があります。
複数の PSP を使う場合、冪等性をどうモデル化しますか?
意図には内部の識別子を、各試行には外部の識別子を使います。
決済は購入を表し、試行は一つの PSP への呼び出しを表します。試行の各コマンドは、対応するプロバイダーでそれぞれ固有の冪等キーを持ちます。
新しい試行をいつ作成できるかはステートマシンが判断します。
オーソリと売上確定に同じキーを使えますか?
通常は使えません。
これらは別々のコマンドであり、ペイロード、エンドポイント、効果が異なる場合があります。
金銭的な意図ごとに固有の識別子を持たせるべきです。
部分返金の場合は?
返金ごとに固有の識別子が必要です。
一つの購入に対して、異なるタイミングで 50 レアルの正当な返金が二回行われる場合、同じ冪等キーを共有することはできません。
一方、最初の返金のリトライでは、その返金自身のキーを再利用する必要があります。
フロントエンドでのダブルクリックはどう防ぎますか?
ボタンを無効化すると UX は改善しますが、保証にはなりません。
ユーザーが二つのタブを開いたり、ネットワークがリクエストを繰り返したり、攻撃者が API を直接呼び出したりする可能性があります。
本当の防御はバックエンドに置く必要があります。
キーをブラウザーで生成してもよいですか?
バックエンドがそれを検証し、セッションや意図に正しく紐づけるのであれば問題ありません。
多くのアーキテクチャでは、スコープを管理するためにサーバー側でキーを生成または確認する方法が好まれます。
重要なのは、インターフェースの挙動だけに頼らないことです。
冪等な意図はどのように永続化しますか?
キー、操作の種類、関連するペイロード、状態、結果、タイムスタンプを含むレコードを作成します。
同じキーが届いたら、アプリケーションはそのレコードを参照します。
操作が完了していれば、対応する結果を返します。処理中であれば、待機するか中間状態を返します。
同じキーのリクエストが二つ同時に届いたらどうなりますか?
これは重要なテストケースです。
システムは相互排他制御か一意性制約によって、一つの実行だけが勝つようにしなければなりません。
並行制御がないと、二つのスレッドが同時に「存在しない」と判断し、請求を二回実行してしまうおそれがあります。
一意性制約で解決しますか?
大いに役立ちます。
キーのスコープに対してデータベースで一意性制約をかければ、同じ意図に二つの行ができるのを防げます。
ただし、外部呼び出しをいつ行うか、クラッシュ後にどう復旧するかの調整は依然として必要です。
check-then-act の問題点は何ですか?
「存在するか確認し、なければ作成する」というパターンです。
並行処理では、どちらかがレコードを作成する前に、二つのプロセスがともに確認を通過してしまうことがあります。
この判断はアトミックに行うか、制約やロックで保護する必要があります。
Outbox パターンはどう役立ちますか?
アプリケーションは、状態の変更と送信用メッセージを同じトランザクションで永続化できます。
その後、ワーカーがメッセージを PSP や他のサービスに届けます。
これにより、データベースには意図が記録されたのに、コマンドを発行する前にプロセスが落ちるという事態を避けられます。
Inbox パターンはどうですか?
コンシューマーが処理済みメッセージの ID を保存し、配信の重複を排除します。
Webhook やキューに有用です。
Outbox と Inbox はフローの異なる部分を解決するもので、API の冪等性とうまく組み合わさります。
冪等性はエラーを返すべきですか、それとも以前の結果を返すべきですか?
契約次第です。
繰り返しがまったく同じ意図であれば、以前の結果を返すのが便利です。
同じキーが異なるパラメーターで届いた場合は、拒否するほうが安全です。
応答全体を保存すべきですか?
役立つこともありますが、サイズ、機密データ、スキーマの変化を考慮する必要があります。
作成済みリソースへの参照を保存し、現在の応答を組み立て直すという選択肢もあります。
どちらを選ぶかは、提供したい契約によって決まります。
エラーを冪等な結果として保存してもよいですか?
実行開始後に発生したエラーについては、そうするプロバイダーもあります。
理屈は通っています。操作が実際に始まり、特定のエラーで終わったのであれば、繰り返しによって新しい実行がひそかに生まれるべきではありません。
ただし、実行前のバリデーションエラーは別の扱いになることがあります。
リトライ可能なエラーとそうでないエラーはどう見分けますか?
分類には意味を考慮する必要があります。
操作が冪等であれば、タイムアウトや 5xx エラーはリトライできる場合があります。バリデーションエラーは通常ペイロードの修正が必要です。カードの拒否をやみくもに繰り返してはいけません。
HTTP ステータスは判断材料の一部にすぎません。
500 が返ったらリトライすべきですか?
自動的にリトライすべきではありません。
まず PSP の契約、冪等性、結果が不明かどうかを確認してください。
結果が 500 であっても冪等な結果として保存するプロバイダーもあります。
アプリケーションは個別のドキュメントに従う必要があります。
429 の場合は?
レート制限には通常、バックオフを伴うリトライが必要です。
それでも、コマンド自体は冪等である必要があります。
プロバイダーが処理前に拒否したのであればリトライは安全かもしれませんが、挙動が不明確な場合は、ドキュメントに記載された保証が優先されます。
指数バックオフとは何ですか?
リトライの間隔を段階的に広げていくことです。
障害時の負荷を軽減します。
ジッターはばらつきを加え、何千ものクライアントが同じ瞬間にリトライするのを防ぎます。
バックオフは冪等性の代わりになりますか?
なりません。
リトライの間隔を空けるだけです。
繰り返すたびに新しい効果が生じるなら、重複がゆっくり発生するだけです。
Webhook にも冪等性は必要ですか?
コンシューマーは冪等でなければなりません。
同じ Webhook が複数回届くことがあります。
同じ event_id を再処理しても、状態変更、残高、フルフィルメントが重複してはなりません。
Webhook の重複はどう排除しますか?
イベントの一意な識別子、または信頼できる派生キーを保存し、一意性制約を使います。
そのうえで、状態遷移を安全に処理します。
プロバイダーが event_id を提供しない場合は、オブジェクトの識別子にバージョンや状態を組み合わせて、慎重に使う必要があるかもしれません。
イベントの順序と冪等性は同じ問題ですか?
違います。
冪等性は重複を防ぎます。順序の制御は状態の後退を防ぎます。
古いイベントが一意であっても、新しいイベントより後に届くことがあります。
ステートマシンが遷移を検証する必要があります。
冪等性と元帳(レジャー)の関係は?
金銭的なイベントごとに、仕訳は一度だけ作成されるべきです。
売上確定の Webhook が二回届いても、元帳の制約によって二重の入金記録を防げます。
仕訳の発生元キーは、冪等性の一つの形です。
冪等性と照合(リコンシリエーション)の関係は?
照合は、防御が機能しなかった場合や、外部のイベントが想定と一致しない場合にそれを検出します。
冪等性があっても、バグは起こり得ます。
照合は第二の防衛線です。
リソースベースの冪等性とは何ですか?
任意のキーの代わりに、既知のリソースを使って操作を行うものです。
たとえば「請求 X の状態をキャンセル済みにする」は、最終結果が同じであれば、本質的に繰り返し可能です。
しかし、新しいオブジェクトを作成する金銭的なコマンドには、通常、明示的なキーが必要です。
キーのスコープはどう決めますか?
キーは、グローバル、加盟店単位、エンドポイント単位、リソース単位のいずれにもできます。
スコープは、正当な操作同士が衝突しないように設定する必要があります。
スコープに merchant_id が含まれていれば、二つの異なる加盟店が同じキー「123」を使っても問題ありません。
冪等キーの衝突とは何ですか?
二つの異なる意図が同じキーを受け取ったときに起こります。
サーバーがパラメーターを比較しなければ、ある操作が別の操作の結果を受け取ってしまうおそれがあります。
エントロピーの高い乱数生成器を使えば偶発的なリスクは下がりますが、アプリケーション側でも論理的な再利用を管理する必要があります。
リトライはどう監査しますか?
attempt_id、冪等キー、HTTP の試行回数、タイムスタンプ、結果、そして可能であればプロバイダーのリクエスト ID を記録します。
こうすれば、何回呼び出しが行われたかを、何回金銭的な効果が生じたかと混同せずに把握できます。
サポートはリトライ回数を見られるべきですか?
障害の調査には役立つことがあります。
サポートがプロトコルの詳細まで知る必要はありませんが、タイムアウトが発生し冪等な復旧が行われたと分かれば、顧客に再度支払いを求めることなく遅延を説明できます。
冪等性はどうテストしますか?
同じリクエストを並行して何度も送ります。
意図を永続化した後、外部呼び出しの前にクラッシュさせます。PSP が処理した後にタイムアウトを起こします。Webhook を再送します。キューを再処理します。
システムは一つの効果に収束しなければなりません。
ペイロードの変更はどうテストしますか?
同じキーで異なる金額を送り、API が拒否するかどうかを確認します。
このケースで、キーを誤って使い回すクライアントのバグが見つかります。
キーの期限切れはどうテストしますか?
プロバイダーのドキュメントに記載された期間を過ぎてから繰り返すシナリオをシミュレートします。
内部アプリケーションは、引き続き操作を止めるのか、明示的に新しい意図を作成するのかを判断する必要があります。
冪等性は公開 API で見えるようにすべきですか?
外部クライアントが効果を伴う操作を実行するのであれば、そうすべきです。
決済 API は、安全なリトライのための明確な仕組みを提供する必要があります。
冪等性を SDK の中だけに隠していては、直接連携するケースをカバーできません。
ヘッダーとボディのフィールド、どちらに置くべきですか?
どちらでも機能します。
キーはビジネスリソースではなくリクエストのセマンティクスに属するため、ヘッダーがよく使われます。
最も重要なのは、契約が一貫していることです。
冪等性はどうドキュメント化しますか?
対応しているエンドポイント、キーのスコープ、保持期間、ペイロードが異なる場合の挙動、並行処理、エラーの種類を説明します。
曖昧なドキュメントは、クライアントに危険な思い込みをさせます。
冪等性で請求は一度だけと保証されますか?
保証されるのは、実装された範囲内で安全に繰り返せることです。
アプリケーションが異なるキーで二つの意図を作成すれば、技術的には正当な請求が二つ発生します。
そのため、ビジネス上の識別子も管理する必要があります。
payment_id と idempotency_key の違いは何ですか?
payment_id はオブジェクトを識別します。
冪等キーはコマンドの意図を識別します。
一つの決済は、そのライフサイクルの中で複数の冪等なコマンドを受け取ることがあります。
キーを別のエンドポイントで再利用してもよいですか?
通常はおすすめできません。
スコープはプロバイダーによって異なり、再利用が競合を引き起こすことがあります。
キーは一つの特定の操作を表すべきです。
冪等性は AI エージェントにどう役立ちますか?
エージェントは失敗の後に計画を立て直し、アクションを繰り返すことがあります。
冪等性がなければ、確認を受け取れなかった自動化が同じ支払いを何度も実行してしまう可能性があります。
お金を動かす自律的なレイヤーには、安全に繰り返せる操作が欠かせません。
こうしたエージェントが購買を行う背景については、エージェンティックコマース(Agentic Commerce)とは?ストアの準備ガイドをお読みください。
冪等性は従来の自動化にどう役立ちますか?
スケジューラー、キュー、ジョブも繰り返し実行されます。
ルールは同じです。インフラは、メッセージが二回以上届き得ることを前提にする必要があります。
PSP の応答後にデータベースが落ちたらどうなりますか?
これは難しいシナリオです。
PSP では効果が生じているのに、アプリケーションは結果を永続化できていません。
冪等キーを事前に永続化していれば、復旧処理で呼び出しを繰り返し、別の効果やリソースを作る代わりに、同じ効果やリソースを取得できます。
キーが永続化されていなかった場合は?
アプリケーションはその操作を識別する手段を失うおそれがあります。
だからこそ、外部呼び出しの前にキーを生成して保存するのが堅実なやり方です。
冪等な操作はどう照合しますか?
保証があっても、照会と照合の仕組みは維持してください。
それらは、外部リソースが内部レコードと一致していることを確認します。
お金が関わる場面では、多層防御が重要です。
冪等性で解決できないことは何ですか?
不正、イベントの順序、不正な状態遷移、金額の誤り、ルーティングの誤り、サービスの停止は解決できません。
解決するのは一つの具体的な問題、つまり効果を重複させずに同じ意図を繰り返すことです。
安全なリトライと新しい試行の違いは何ですか?
安全なリトライは、同じ識別子で同じ意図を繰り返すことです。
新しい試行は、前回が既知の結果で終わったか、ポリシーが先へ進むと判断したために、新しい実行を生み出すことです。
両者を混同することは、重複の一般的な原因です。
冪等性は API の金銭的な契約の一部です
決済 API は、完璧なネットワークを前提にすることはできません。
接続は失敗し、クライアントはリトライし、キューは再送し、プロセスは再起動します。
正しい設計は、繰り返しを想定内の挙動に変えます。
冪等キー、ステートマシン、制約、照合が連携すれば、プラットフォームは耐障害性を二重請求に変えることなく障害から復旧できます。