API에서 Idempotency Key는 왜 필요하며 어떻게 동작하나요?

Idempotency Key는 같은 요청이 여러 번 도착해도 서버가 한 번만 처리하도록 돕는 식별자입니다. 결제, 주문 생성, 포인트 적립처럼 중복 실행되면 치명적인 API에서 특히 중요합니다.

클라이언트는 요청마다 고유한 key를 생성해 헤더로 보냅니다. 서버는 이 key와 요청 정보를 저장하고, 같은 key가 다시 오면 작업을 새로 수행하지 않고 이전 결과를 반환합니다.

POST /payments
Idempotency-Key: 9f82b7a4-7f2e-4c2d-9a74
Content-Type: application/json

동작 흐름은 보통 이렇습니다.

1. 처음 받은 key면 요청을 처리하고 결과를 저장합니다.
2. 같은 key가 다시 오면 저장된 응답을 반환합니다.
3. 같은 key인데 요청 본문이 다르면 충돌로 보고 에러 처리합니다.
4. key 저장 기간을 정해 오래된 기록은 정리합니다.

핵심은 네트워크 실패와 서버 처리 실패를 구분하기 어렵다는 현실입니다. 클라이언트 입장에서는 타임아웃이 났지만 서버에서는 결제가 성공했을 수 있습니다. Idempotency Key는 안전한 재시도를 가능하게 만들어 사용자 경험과 데이터 정합성을 함께 지켜줍니다.