사용자가 결제 버튼을 다시 눌렀을 때 네트워크는 두 요청을 보낼 수 있습니다. 화면에서 버튼을 비활성화해도 모바일 재전송이나 프록시 재시도가 남습니다. 멱등 키는 같은 의도를 같은 결과로 처리하게 하지만 수명과 범위를 잘못 정하면 다른 요청까지 묶을 수 있습니다.
같은 의도의 경계를 정한다
멱등 키는 한 고객의 한 작업 시도를 식별해야 합니다. 주문을 새로 만드는 두 의도에는 다른 키를 주고, 같은 작업의 재시도에는 같은 키를 재사용합니다.
키만 같고 금액이나 수신자가 달라지면 이전 결과를 돌려줄지 오류로 거절할지 정해야 합니다. 일반적으로 요청 내용의 안정된 지문을 함께 비교하는 방식을 검토합니다.
처리 중 상태를 저장한다
첫 요청이 아직 실행 중인데 두 번째 요청이 들어올 수 있습니다. 결과가 확정되기 전 같은 키를 받은 서버는 대기, 중복 처리 거절, 현재 상태 반환 중 명확한 정책을 택해야 합니다.
작업 결과뿐 아니라 실패 유형도 고려합니다. 일시적 실패를 같은 키로 재시도할 수 있는지, 이미 외부 결제가 실행됐는지에 따라 대응이 달라집니다.
보관 수명을 업무에 맞춘다
키를 너무 빨리 지우면 늦게 도착한 재시도가 새 작업으로 처리될 수 있습니다. 너무 오래 보관하면 저장 비용이 늘고 의도치 않은 키 재사용이 충돌할 수 있습니다.
클라이언트의 재시도 기간, 결제 정산, 메시지 지연을 보고 보관 기간을 정합니다. 특정 서비스 제공자의 키 보존 정책을 그대로 다른 업무에 복사하지 않습니다.
가상 사례: 결제 응답만 유실
결제는 성공했지만 사용자에게 응답이 도착하지 않았다고 가정해 봅시다. 사용자가 다시 누르면 같은 키로 기존 결과를 확인해야 이중 청구를 피할 수 있습니다.
결제사에서도 멱등성 기능을 제공한다면 내부 키와 외부 요청 ID를 연결합니다. 이 사례는 가상의 설명이며 특정 결제사의 보장 범위를 일반화하지 않습니다.
중복 여부를 관찰한다
같은 키 재시도, 내용 불일치, 처리 중 충돌과 키 만료 후 재요청을 따로 집계합니다. 어떤 클라이언트가 반복해서 잘못된 키를 쓰는지도 확인합니다.
멱등성은 한 API 경로의 중복을 줄이지만 전체 업무의 모든 부작용을 자동으로 막지는 않습니다. 이메일 발송이나 재고 차감 같은 후속 단계에도 고유 작업 ID를 전달해야 합니다.
현장에 적용할 때의 순서
- 한 사용자 행동에 키 하나를 부여한다
- 동일 키의 요청 지문을 확인한다
- 결과·처리 중·만료 상태를 나눈다
주의할 실패: 같은 키에 다른 금액이 들어왔는데 이전 성공 응답을 반환하면 거래 내역을 잘못 보여 준다.
관찰할 지표: 키 충돌과 처리 중 재시도, 만료 뒤 요청을 구분해 본다.
적용 전 체크리스트
- 키가 사용자·작업·요청 내용에 묶이는가
- 처리 중 중복 요청의 행동이 정의돼 있는가
- 키 만료가 실제 재시도 기간보다 충분한가
참고 자료
Stripe API Idempotent Requests. Stripe 문서는 해당 API의 멱등 요청 동작을 설명합니다. 본문의 키 수명과 충돌 정책은 각 시스템에 맞춰 결정해야 합니다.
이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.
#멱등키 #API설계 #결제API #중복요청 #재시도 #백엔드 #분산시스템 #정산 #트랜잭션 #데이터정합성
