冪等キー(Idempotency-Key)とは?二重決済・二重登録を防ぐAPI設計と実装のポイント

起きる問題:「結果が分からない」から、再送した

オンラインで、決済のリクエストを送ったとします。通信が不安定で、応答が返ってこない。実際には、サーバーは処理を終えていたのかもしれませんし、届いていなかったのかもしれません。

利用者やプログラムは、結果が分からないので、もう一度、同じリクエストを送ります。すると、すでに処理されていた場合、二重に決済されてしまいます。

この問題を防ぐ考え方が、冪等性です(冪等性とは)。そして、決済や登録のように、本来は、繰り返すと結果が変わってしまう操作を、安全に再送できるようにする仕組みが、冪等キーです。

冪等キーの考え方

冪等キーは、「この操作は、これです」という、一意の印です。

この仕組みで、何度送っても、処理は1回だけになります。

具体的な流れ(例)

HTTPでは、キーをヘッダーに付けて送る設計が、決済などのAPIで、よく使われます。

POST /payments Idempotency-Key: 3f2a9c1e-...(操作ごとに作った、一意の値)

1. 1回目のリクエスト:サーバーが、決済を処理し、キーと結果(成功)を保存する。応答は、通信エラーで届かなかった
2. 再送(同じキー):サーバーは、キーが保存されていることを確認し、決済は行わず、保存してあった結果を返す

サーバー側で決めること

サンプルコード(考え方の例)

考え方を示す、簡単な例です。実際の運用では、データベースの制約や、同時実行への対応を、きちんと設計してください。

# 保存先の例:キーごとに「リクエストの内容」と「結果」を持つ
saved = {}

def create_payment(idempotency_key, request):
    if idempotency_key in saved:
        record = saved[idempotency_key]
        if record["request"] != request:
            # 同じキーで、内容が違う → エラー
            raise ValueError("同じキーで、異なる内容のリクエストです")
        return record["response"]      # 前の結果を、そのまま返す

    response = do_payment(request)     # 初回のみ、実際の処理を行う
    saved[idempotency_key] = {"request": request, "response": response}
    return response

実際のシステムでは、「保存」と「処理」が、確実にセットで行われるようにする必要があります。たとえば、キーをデータベースの一意制約で、二重に登録できないようにし、処理と保存を、**1つの取引(トランザクション)**にまとめる設計が、考えられます。

クライアント側の使い方

• 操作ごとに、一意のキーを作る(UUIDのような、重複しにくい値)
• 再送の時は、同じキーを使う
• 新しい操作には、新しいキーを使う
• 再送の方法は、APIのタイムアウトとリトライの決め方と、組み合わせて設計する

よくある落とし穴

冪等キー以外の方法

冪等キーを使わなくても、操作が、もともと冪等になる設計ができる場合もあります。

• 注文番号などを、クライアント側で先に決め、データベースの一意制約で、二重に登録できないようにする
• 「注文を作る」ではなく、「この番号の注文を、この状態にする」という形の操作にする

どの方法が合うかは、扱う操作の性質によって異なります。

まとめ

• 冪等キーは、同じ操作の再送を見分けるための、一意な印
• サーバーは、キーと結果を保存し、同じキーなら、前の結果を返す
• 同じキーで内容が違う場合は、エラーにする
• 落とし穴は、キーの作り直し・保存期限・処理中の同時リクエスト・結果の保存漏れ
• 再送は、タイムアウト・リトライの設計と、セットで考える

API連携の他の確認事項は、API連携が「両方正常なのに繋がらない」時の確認5項目や、APIをループで呼ぶ時の3つの約束をご覧ください。