AI 생성결제 API 만드는 사람이라면 — 재시도 한 번이 중복 결제가 되지 않게 하는 법

🤖 AI 생성 콘텐츠 — 이 글은 AI가 자료를 수집하고 초안을 작성했으며, 발행 전 누슘 운영자가 검수했습니다.

멱등성은 같은 요청을 반복해도 의도된 효과가 한 번과 같은 성질이다. 결제 API는 Idempotency-Key와 결과 저장으로 중복 처리를 막을 수 있다.

결제 버튼을 눌렀는데 화면이 멈췄습니다. 사용자는 다시 누릅니다. 첫 요청이 실패한 걸까요, 서버에서는 성공했는데 응답만 사라진 걸까요? 이 애매한 순간이 중복 결제를 만듭니다. 멱등성 키는 같은 택배 주문에 같은 접수번호를 붙여 “이미 처리한 건입니다”라고 알아보게 하는 장치입니다.

목차

• 멱등성은 정확히 무엇인가
• Idempotency-Key는 어떻게 동작하나
• 구현할 때 자주 놓치는 함정

멱등성은 정확히 무엇인가?

RFC 9110은 동일한 요청을 여러 번 했을 때 서버에 의도된 효과가 한 번 요청한 것과 같다면 해당 메서드를 멱등적이라고 정의합니다. 표준이 정의한 PUT, DELETE, 그리고 안전한 메서드들은 멱등적입니다. POST와 PATCH는 자동으로 멱등성이 보장되지 않습니다.

여기서 응답까지 완전히 같아야 한다는 뜻은 아닙니다. 첫 DELETE는 성공을, 다음 요청은 이미 없다는 결과를 줄 수 있습니다. 중요한 것은 서버 상태에 대한 의도된 효과입니다.

Idempotency-Key는 어떻게 동작하나?

클라이언트는 논리적으로 같은 작업에 고유 키를 붙입니다. 서버는 첫 요청이 실제 실행되면 키, 요청 내용, 결과를 저장합니다. 같은 키가 다시 오면 작업을 또 실행하지 않고 저장된 결과를 돌려줍니다.

Stripe API 문서는 객체 생성·수정 때 멱등성 키를 사용해 연결 오류 뒤에도 안전하게 재시도할 수 있다고 안내합니다. 첫 요청의 상태 코드와 본문을 저장하며, 같은 키의 후속 요청에는 500 오류를 포함해 같은 결과를 반환한다고 명시합니다. Stripe 구현에서는 키를 최대 255자로 받고, 최소 24시간이 지난 키를 제거할 수 있다고 설명합니다. 이 수치는 Stripe의 정책이지 모든 API의 국제 표준은 아닙니다.

구현할 때 자주 놓치는 함정

첫째, 키만 저장하고 요청 내용을 비교하지 않으면 위험합니다. 같은 키로 금액이나 상품이 다른 요청이 오면 오류를 내야 합니다. Stripe도 원래 요청과 매개변수를 비교한다고 설명합니다.

둘째, “결제 완료 후 키 저장”처럼 순서를 잘못 잡으면 동시 요청 둘이 모두 실행될 수 있습니다. 키 예약과 작업 실행, 결과 기록을 원자적으로 다루거나 데이터베이스의 고유 제약과 트랜잭션을 이용해야 합니다.

셋째, 키 보존 기간보다 오래 재시도하면 새 요청으로 처리될 수 있습니다. 클라이언트 재시도 정책과 서버 보존 기간을 함께 문서화하세요. 넷째, 멱등성은 인증이나 사기 탐지를 대신하지 않습니다. 같은 주문의 중복 실행을 막는 기능이지, 그 주문 자체가 정당한지 판단하는 장치는 아닙니다.

자주 묻는 질문 (FAQ)

Q. 멱등성이란 무엇인가요? A. 같은 요청을 여러 번 보내도 서버에 의도된 효과가 한 번 보낸 것과 같게 유지되는 성질입니다. 네트워크 오류 뒤 안전한 재시도를 설계할 때 중요합니다.

Q. POST 요청도 멱등적으로 만들 수 있나요? A. HTTP 표준이 POST의 멱등성을 자동 보장하지는 않지만, 애플리케이션이 멱등성 키와 결과 저장을 구현해 같은 논리 작업의 중복 실행을 막을 수 있습니다.

Q. UUID만 보내면 중복 결제가 막히나요? A. 아닙니다. 서버가 키를 원자적으로 예약하고 요청 내용을 비교하며 첫 결과를 저장·재사용해야 합니다. 키 생성만으로는 충분하지 않습니다.

마치며

분산 시스템에서는 “응답이 안 왔다”와 “실행이 안 됐다”가 같은 말이 아닙니다. 멱등성 키는 이 틈을 메우는 작지만 강력한 약속입니다. 주문·결제 API의 재시도 흐름을 그려보고, 키 저장과 실행이 정말 한 덩어리로 처리되는지 점검해보세요.

참고자료

• RFC 9110 — HTTP Semantics, Idempotent Methods
• Stripe API — Idempotent requests
• MDN — Idempotent

태그: #멱등성 #IdempotencyKey #API설계 #중복결제 #HTTP #재시도 #Stripe