멱등성 키

Idempotency Key

재시도 요청에 같은 키를 붙여 한 번 처리한 생성 작업이 중복 실행되지 않게 합니다.

···
html
<div class="viz"><h3>POST /orders · KEY K7</h3><div class="row"><div class="box">try 1<br>try 2</div><span class="arrow">→</span><div class="box" id="gate">key store</div><span class="arrow">→</span><div class="box">orders <b id="count" class="accent">0</b></div></div><div class="muted" id="result">processing…</div></div>
css
.viz{width:94%;height:88%;max-width:960px;padding:clamp(10px,2vmin,18px);border:1px solid var(--line);border-radius:14px;background:var(--surface);font:600 clamp(12px,1.35vw,16px)/1.35 var(--font-sans,system-ui,sans-serif);display:flex;flex-direction:column;gap:clamp(7px,1.8vmin,13px);overflow:hidden}.viz h3{margin:0;color:var(--accent);font:700 clamp(12px,1.35vw,16px)/1.2 var(--font-sans,system-ui,sans-serif);letter-spacing:.04em}.viz .row{display:flex;align-items:center;justify-content:center;gap:clamp(5px,1.4vmin,12px);flex:1;min-height:0}.viz .box{padding:clamp(5px,1.5vmin,12px);border:1px solid var(--line);border-radius:9px;background:var(--bg);text-align:center}.viz .muted{color:var(--muted)}.viz .accent{color:var(--accent)}.viz .code{font-family:ui-monospace,monospace}.viz .pill{padding:3px 7px;border:1px solid var(--line);border-radius:99px;white-space:nowrap}.viz .active{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 12%,var(--surface))}.viz .arrow{color:var(--accent);font:700 18px ui-monospace,monospace}#gate{transition:background .3s,border-color .3s}#gate.hit{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 15%,var(--surface))}
js
let retry=false;function draw(){retry=!retry;document.getElementById('count').textContent='1';document.getElementById('gate').classList.toggle('hit',retry);document.getElementById('result').textContent=retry?'attempt 2 · cached result · no new order':'attempt 1 · order created'}draw();setInterval(draw,1600)

멱등성 키는 클라이언트가 작업 시도에 부여하는 고유 식별자입니다. 서버는 키와 처리 결과를 일정 기간 보관하고, 같은 키로 재시도되면 저장된 결과를 반환합니다. 네트워크 응답이 사라져 클라이언트가 성공 여부를 모를 때 유용합니다.

데모에서 두 POST 요청은 같은 키를 공유하고 주문은 하나만 만들어집니다. 서버는 키의 범위·보관 기간·동일 키에 다른 본문이 왔을 때의 정책을 정해야 합니다.

언제 쓰나

결제·주문처럼 재시도가 중복 부작용을 만들 수 있는 생성 요청에 씁니다.

페이지로 열기 ↗