멱등성
Idempotency · 멱등 키
멱등성은 같은 요청을 한 번 보내거나 여러 번 반복해도 의도한 최종 상태가 달라지지 않는 성질입니다. 네트워크 오류로 재시도해야 하는 API에서 중복 결제나 중복 생성 같은 부작용을 막는 핵심 설계 기준입니다.
AI 보조 조사·작성 후 원문과 대조한 설명입니다. 사례·계산은 별도 출처 표기가 없는 한 이해를 위한 가상 예시이며 실제 고객 성과가 아닙니다.
멱등성이 필요한 이유
클라이언트가 요청을 보낸 뒤 응답을 받지 못했다고 해서 서버가 처리하지 않은 것은 아닙니다. 서버는 작업을 완료했지만 응답만 끊겼을 수 있고, 이때 같은 생성 요청을 그대로 다시 보내면 결과가 두 개 생길 수 있습니다. 멱등한 설계는 재시도를 허용하면서도 이미 처리한 요청을 식별해 같은 결과를 돌려주거나 추가 실행을 막으므로, 클라이언트와 서버가 응답 유실 뒤에도 같은 업무를 새 작업으로 오해하지 않게 해 줍니다. IETF RFC 9110, Idempotent Methods는 같은 요청을 여러 번 수행해도 서버에서 의도한 효과가 한 번 수행한 것과 같으면 멱등하다고 정의하고 안전한 메서드, PUT, DELETE를 멱등 메서드로 설명합니다.
HTTP 메서드와 업무 멱등성
HTTP 규격에서는 PUT, DELETE와 안전한 메서드를 멱등한 것으로 정의합니다. 하지만 메서드 이름만으로 실제 업무 부작용이 사라지는 것은 아닙니다. 예를 들어 같은 PUT 요청이 최종 자원 상태는 같게 만들더라도 매번 알림을 보내도록 구현했다면 알림은 중복될 수 있습니다. 반대로 POST도 서비스가 멱등 키를 지원하면 안전한 재시도 흐름을 만들 수 있습니다.
| 요소 | 역할 |
|---|---|
| 멱등 키 | 같은 업무 요청을 식별하는 고유 키입니다. |
| 요청 비교 | 같은 키에 다른 매개변수가 들어오면 오류로 처리합니다. |
| 결과 보관 | 처음 처리한 상태와 응답을 일정 기간 저장합니다. |
| 재시도 정책 | 시간 초과, 서버 오류 등 재시도 가능한 조건을 제한합니다. |
가상 결제 예시
가상 쇼핑몰이 주문 123의 결제를 요청하며 주문별 멱등 키를 보냈다고 하겠습니다. 통신이 끊겨 같은 키로 다시 요청하면 결제 서비스는 새 결제를 만들지 않고 최초 처리 결과를 반환할 수 있습니다. 반대로 같은 키로 금액을 바꿔 보내면 이전 요청과 충돌하므로 실패시켜야 합니다. 키는 무작위 문자열이라는 형식보다 같은 업무 시도에 같은 키, 다른 업무에는 다른 키라는 생성 범위가 더 중요합니다. Stripe API Docs, Idempotent requests는 POST 요청에 멱등 키를 보내 최초 상태 코드와 본문을 저장하고, 같은 키의 매개변수가 달라지면 오류를 내는 구체적 동작을 설명합니다.
멱등성은 중복 제거와 가깝지만 동일하지 않습니다. 중복 제거가 사후에 비슷한 레코드를 찾아 합칠 수도 있다면, 멱등성은 요청 처리 경계에서 같은 작업의 반복 실행을 제어하는 성질입니다.
자주 묻는 질문
- 멱등성과 중복 제거는 같은가요?
- 아닙니다. 멱등성은 같은 요청을 반복해도 최종 상태가 달라지지 않게 하는 처리 성질이고, 중복 제거는 저장된 레코드나 이벤트의 중복을 판별하는 작업입니다.
- POST 요청은 멱등할 수 없나요?
- HTTP 의미상 POST 자체는 일반적으로 멱등하지 않지만, API가 멱등 키와 결과 재사용을 지원하면 특정 업무 작업을 안전하게 재시도할 수 있습니다.
- 멱등 키는 얼마나 오래 보관해야 하나요?
- 공급사와 업무 흐름에 따라 다릅니다. 재시도 가능 기간, 결제 확정 시간, 저장 비용을 고려하고 해당 API의 공식 보관 규칙을 확인해야 합니다.
- 같은 키에 다른 값을 보내면 어떻게 해야 하나요?
- 처음 요청과 매개변수가 다르면 새 작업으로 처리하지 말고 충돌 오류를 내는 방식이 일반적입니다. 그래야 키 재사용으로 인한 잘못된 결과를 막을 수 있습니다.
출처와 확인 범위
- IETF RFC 9110, Idempotent Methods · RFC Editor / IETF · 확인 2026-10-27
같은 요청을 여러 번 수행해도 서버에서 의도한 효과가 한 번 수행한 것과 같으면 멱등하다고 정의하고 안전한 메서드, PUT, DELETE를 멱등 메서드로 설명합니다.
확인 범위: HTTP 메서드 의미에 관한 규격이며 개별 서비스의 멱등 키 보관 기간이나 응답 재사용 규칙을 정하지 않습니다.
- Stripe API Docs, Idempotent requests · Stripe Documentation · 확인 2026-10-27
POST 요청에 멱등 키를 보내 최초 상태 코드와 본문을 저장하고, 같은 키의 매개변수가 달라지면 오류를 내는 구체적 동작을 설명합니다.
확인 범위: Stripe API의 구현 규칙이며 키 길이, 보관 시간, 실패 응답 처리 방식을 다른 공급사에 일반화하지 않습니다.