Idempotency Key
冪等鍵
01你是不是遇到這個 / THE SYMPTOM
使用者付款時手抖點兩下、或網路逾時重送，結果被扣了兩次款 / 建立了兩筆一樣的訂單；我想確保「同一個操作就算被送很多次，也只會真的執行一次」
↑ 如果你點頭了，你要的關鍵字就是 Idempotency Key。
02這是什麼 / DEFINITION
Idempotency Key 是請求方產生的一組唯一識別碼（隨請求一起送），後端用它來判斷「這個操作我是不是已經做過了」：做過就直接回上次的結果，沒做過才真的執行——確保重送不會造成重複副作用。
03什麼時候用 / WHEN TO USE
任何「重複執行會出事」的寫入操作：刷卡扣款、建立訂單、轉帳、發送通知、處理 webhook（因為對方可能重送）。讀取操作天生就冪等、不需要。
04怎麼跟 AI 說 / HOW TO ASK
直接複製這句、貼進 Claude Code / Cursor / Copilot / ChatGPT：
幫我在建立訂單的 API 支援 idempotency key：用戶用同一把 key 重送時，回傳第一次的結果而不是再建一筆訂單，key 存進資料庫並設唯一索引
05常見坑 / WATCH OUT
⚠ 冪等的重點在「副作用只發生一次」，不是「回應一定相同」。實作常見坑：要把 key 連同結果存起來（通常配資料庫唯一索引或 Redis），並處理「第一次還在處理中、第二次就來了」的併發競態，否則照樣雙重執行。GET/PUT/DELETE 在 HTTP 語意上本就該冪等，POST 才特別需要這把 key。
06相關的詞 / RELATED