作成APIの応答が返らなかったとき、クライアントには「作成前に失敗した」のか「作成済みだが応答を失った」のか分かりません。そこで同じ要求を再送すると、二つ目のデータができる可能性があります。
Idempotency Keyは、その再送を同じ仕事へ結び付ける識別子です。実際に重複を防ぐには、サーバーがキー、入力、処理結果をどう保存するかまで決める必要があります。
ローカルD1で、メモ作成と結果保存を同じbatch()へ入れ、応答消失、同時実行、入力の食い違い、記録の削除を確認しました。確認日は2026年9月11日です。これは説明用の実装で、既存アプリへ導入した記録ではありません。
同じキーで、何を同じとみなすか
Stripeの冪等な要求に関する説明では、最初の要求のstatus codeとbodyを保存し、同じキーの再要求でその結果を返します。入力が一致するかも比較し、記録を削除した後に同じキーが来れば新しい要求として扱います。
ここから分かるのは、ヘッダー名だけで仕組みが成立しているわけではないことです。また、これはStripeの仕様です。独自APIに同じ名前のヘッダーを付けても、その保存や比較が自動で追加されるわけではありません。
今回の実験では、キーの範囲を次の三つで決めました。
認証済みの操作主体 / 操作の種類と版 / クライアントのキー
actor-a / create-note:v1 / key-a
同じkey-aでも、別の主体なら別の作成を許します。同じ主体が同じ操作へ再送した場合は、元の入力と結果へ戻します。操作主体は実験関数へ渡す信頼済みの引数で、HTTPリクエストからの認証処理は実装していません。
入力の指紋と、返す結果を保存する
結果保存用のテーブルは次の形です。
CREATE TABLE request_result (
actor TEXT NOT NULL,
operation TEXT NOT NULL,
request_key TEXT NOT NULL,
fingerprint TEXT NOT NULL,
status_code INTEGER NOT NULL,
body TEXT NOT NULL,
PRIMARY KEY(actor, operation, request_key)
);
fingerprintには、今回の入力であるtitleをJSONへしたもののSHA-256を入れます。扱う入力を一つに限定した実験なので、任意のJSONをそのままハッシュすればよいという一般的な正規化方法は示していません。実APIでは、処理結果に影響する入力を取りこぼさないようにします。
既存のキーがあれば指紋を比較し、一致すれば保存した結果を返します。違う入力なら、この実装ではstatus値409を持つエラーにしました。これは独自の実験上の選択で、Stripeと同じエラー契約を再現したものではありません。
キーがなければ、作成するメモのIDを生成し、そのIDを含む応答とメモ本体を保存します。
await db.batch([
db.prepare('INSERT INTO request_result VALUES (?, ?, ?, ?, ?, ?)')
.bind(actor, operation, key, fingerprint, 201, JSON.stringify(body)),
db.prepare('INSERT INTO note VALUES (?, ?, ?)')
.bind(body.id, actor, title),
]);
bodyは生成したIDとtitleを持つオブジェクトです。この抜粋の前後を含む実験コードでは、保存済みの結果を読む分岐と競合時の再読込みも実装しています。
D1のbatch仕様は、この二つの書き込みを同じトランザクションとして扱う根拠になります。結果だけ残り、メモ本体の作成が失敗した状態を避けるためです。
「先に存在確認」だけで同時実行を防がない
単純な事前確認では、二つの要求がどちらも「キーがない」と読む可能性があります。今回のテストでは、その状況になるように待ち合わせを入れました。
要求A: キーなしを確認 ─┐
├─ 両方の確認が済むまで待つ
要求B: キーなしを確認 ─┘
その後、両方がbatchを実行する
同じ複合主キーへのINSERTが競合するため、片方のbatchだけが新規作成として成功します。もう片方は保存済みの結果を読み直し、入力の指紋を比較してから返します。
実験では、二つの事前確認が両方とも未登録だったこと、メモが1件だけできたこと、返るbodyが同じことをassertしました。どちらかがたまたま先に済んだケースだけを見て、同時実行に対応したとは判断していません。
事前のSELECTは既存結果を早く返すために使えますが、最後に重複を止めるのは一意制約と原子的な書き込みです。プロセス内のMapだけでは、別プロセスからの要求を同じ条件で扱えません。
応答を失った後も、同じIDへ戻れるか
作成がコミットした後に例外を投げ、クライアントが成功結果を受け取れなかった状態を模しました。実HTTP通信を途中で切断したテストではありません。
その後、同じ主体・キー・titleでもう一度実験関数を呼びました。返されたbodyとstatus値201は最初と一致し、メモは1件のままでした。作成済みという印だけでなく結果を保存しているため、再送した呼び出し元が同じIDを知れます。
確認したケース全体は次のとおりです。
| 条件 | 結果 |
|---|---|
| コミット後に応答を失い、同じ入力を再送 | 同じbodyと201、メモ1件 |
| 同じ主体・キーでtitleを変更 | 409として拒否、メモ1件のまま |
| 別の主体が同じキーを使用 | 別のメモを作成、合計2件 |
| 二つの要求が両方ともキーなしを確認 | メモ1件、同じbody、新規1回と再利用1回 |
| メモのCHECK制約で作成が失敗 | メモ0件、保存結果0件 |
| 保存結果を削除してから同じ要求を再送 | 新しいメモができ、合計2件 |
最後のケースは、保持期間が終わって記録がなくなった状態を、明示的なDELETEで再現したものです。TTLによる自動削除は実装していません。キーを永久に覚えている設計ではないなら、期限後に同じ要求が来たときの扱いをAPIの利用側にも伝える必要があります。
この実装が保存するのは、成功した作成の結果だけ
実行環境はNode.js v24.15.0、Wrangler 4.81.1、Miniflare 4.20260409.0です。リモートbindingは無効で、ローカルD1と合成データだけを使いました。
今回の実装は、メモ本体と成功結果を同時に保存します。Stripeの資料にあるような、実行開始後の失敗結果も含めて保存する契約は再現していません。認証、入力検証、HTTPヘッダーや応答全体の再利用、保持期間の運用も別に必要です。
また、同じbatchに入るのはD1の書き込みです。外部への通知やファイル送信を、この仕組みだけで一回にすることはできません。外部処理を含めるなら、その処理が何をキーとして結果を再利用するかも確認します。
キーの記録が消えた後も同じ業務データを重複させてはいけないなら、その条件はメモのような業務テーブル側にも必要です。要求の再送をまとめる期間と、業務上同じデータを作ってはいけない期間は一致するとは限りません。
再送への対応をレビューするときは、キーの有無に加えて、範囲、入力一致、同時作成、結果の再利用、記録を消した後の五つを確認します。これらの結果から、そのAPIが防げる二重処理の範囲を説明できます。