idempotency란 무엇이며, idempotency key는 retry를 어떻게 안전하게 만드는가?

Question

IT Interview Practice · Accepted Answer

**Idempotency**는 어떤 연산을 **여러 번 수행해도 한 번 수행한 것과 같은 효과**를 낸다는 뜻이다. 네트워크가 신뢰할 수 없기 때문에 중요하다: client가 request를 보냈는데 response가 도착하지 않으면, server가 그것을 처리했는지 알 수 없다. retry하면, idempotent하지 않은 연산은 두 번 실행될 수 있다.

## 문제

```text
Client ──POST /payments {$100}──▶ Server   (charges $100 ✓)
Client ◀────────X (timeout)────── Server   (response lost)
Client ──POST /payments {$100}──▶ Server   (charges $100 AGAIN ✗ → $200!)
```

`GET`, `PUT`, `DELETE`는 본래 idempotent해서 retry가 안전하다. `POST`는 **아니다** — 바로 여기서 이중 청구와 중복 주문이 나온다.

## 해법: idempotency key

client가 논리적 연산에 대해 **고유한 key**(보통 UUID)를 생성해 헤더로 보낸다. server는 그 key를 결과와 함께 저장하고, 같은 key가 다시 오면 재실행하는 대신 **저장된** 결과를 반환한다.

```http
POST /payments HTTP/1.1
Idempotency-Key: 5f2b8c1e-3a4d-4e6f-9c0b-1a2b3c4d5e6f
Content-Type: application/json

{ "amount": 100, "currency": "usd" }
```

```text
Idempotency-Key가 있는 request를 받은 server 로직:
  1. key를 저장소(예: Redis/DB)에서 조회한다.
  2. 발견되면 → 저장된 response를 반환한다(재청구 없음).       ← retry 경우
  3. 없으면  → 처리하고, (key → response)를 저장한 뒤 반환한다.
  (동시 retry가 이중 실행되지 않도록 3단계를 transaction / lock으로 감싼다.)
```

retry 시 **같은 key**는 같은 `200`과 같은 payment를 낸다 — 고객은 한 번만 청구된다. 이것이 바로 Stripe API가 동작하는 방식이다.

## 왜 중요한가

이 질문은 happy path를 설계하는 엔지니어와 **실패**를 설계하는 엔지니어 — production 신뢰성의 본질 — 를 가른다. 분산 시스템은 timeout과 부분 실패가 *일어날 것*임을 보장하므로, side effect가 있는 모든 엔드포인트 — 결제, 주문, 송금 — 에는 retry 전략이 필요하고, `POST`에 "그냥 retry"는 위험하다. 면접관은 두 부분의 통찰을 듣고 싶어 한다: 첫째, idempotency는 *설계로 넣을 수 있는* 속성이라는 것(`PUT`/`DELETE`는 본래 안전하게 만들고, 그럴 수 없는 `POST`에는 **idempotency key**를 준다). 둘째, 미묘한 동시성 세부 사항 — 동시에 도착한 두 retry가 둘 다 실행되어서는 안 되므로 key 확인과 쓰기에 lock이나 unique constraint가 필요하다는 것. 이를 올바르게 하는 것이 고객을 한 번 청구하는 것과 두 번 청구하는 것의 차이이며, 그래서 진지한 모든 결제·커머스 API가 이를 구현한다.

문제

해법: idempotency key

왜 중요한가

관련 질문