분산 API는 곤란한 방식으로 실패합니다. 서버가 요청을 이미 처리한 뒤에 연결이 끊길 수 있습니다. 공급자는 계속 처리 중인데 게이트웨이가 타임아웃을 반환할 수도 있습니다. 응답을 받지 못한 클라이언트는 호출을 반복합니다. 큐는 같은 메시지를 다시 보낼 수 있습니다. 사용자가 결제 버튼을 두 번 누를 수도 있습니다.
일반적인 작업에서는 반복이 중복 작업으로 끝날 수 있습니다. 하지만 결제에서는 금전적 영향이 두 번 발생할 수 있습니다.
멱등성(idempotency)은 같은 의도를 여러 번 보내더라도 반복할 때마다 새로운 효과가 생기지 않도록 하기 위해 존재합니다. 탄력적인 금융 API를 만드는 데 가장 중요한 도구 중 하나이지만, 가장 많이 오해받는 도구 중 하나이기도 합니다.
작업이 멱등하다는 것은 무슨 뜻인가요?
멱등한 작업은 반복해서 실행해도 첫 번째 유효한 실행이 만든 효과 이상으로 결과가 바뀌지 않는 작업입니다.
100헤알을 청구하는 것이 의도라면, 같은 식별자로 같은 요청을 반복해도 서로 독립된 청구가 두 건 생겨서는 안 됩니다.
반복은 같은 논리적 작업으로 인식되어야 합니다.
멱등성은 API가 항상 똑같이 응답한다는 뜻인가요?
세부 사항까지 반드시 같을 필요는 없지만, 비즈니스 효과는 단 한 번이어야 합니다.
어떤 공급자는 원래 응답을 저장해 두었다가 다시 반환합니다. 어떤 공급자는 생성된 리소스를 반환합니다. 두 번째 효과가 생기지 않는다는 것만 보장하는 곳도 있습니다.
정확한 계약은 API 문서에서 확인해야 합니다.
멱등성 키란 무엇인가요?
클라이언트가 특정한 의도를 나타내기 위해 제공하는 식별자입니다.
서버는 키를 처음 받으면 작업을 실행하고 그 결과를 키에 연결합니다. 반복 요청이 오면 그 의도가 이미 처리되었다는 것을 알아보고 다시 실행하지 않습니다.
키는 '이 사용자'가 아니라 '이 논리적 작업'을 나타내야 합니다.
키는 누가 생성해야 하나요?
보통은 비즈니스 의도를 알고 있는 시스템입니다.
백엔드가 결제 시도를 생성한다면, PSP를 호출하기 전에 그 시도에 대한 고유 키를 생성할 수 있습니다.
중요한 것은 같은 의도에는 같은 키를 재사용하고, 새로운 의도에는 다른 키를 쓰는 것입니다.
order_id를 멱등성 키로 써도 되나요?
상황에 따라 다릅니다.
하나의 주문에 해당 유형의 작업이 하나만 있을 수 있다면 통할 수도 있습니다.
하지만 하나의 주문에는 여러 번의 시도, 매입, 환불, 변경이 있을 수 있습니다. 이 경우 order_id만 사용하면 서로 다른 정당한 작업까지 막을 수 있습니다.
키에는 명령에 맞는 올바른 세분성이 담겨야 합니다.
무작위 UUID면 충분한가요?
충돌 위험은 해결하지만 의미 문제는 해결하지 못합니다.
재시도할 때마다 새 UUID를 만든다면 멱등성의 이점이 사라집니다.
키는 첫 호출 전에 의도와 함께 저장되어 있어야 재사용할 수 있습니다.
키는 언제 생성해야 하나요?
외부 작업을 실행하기 전입니다.
PSP 응답을 받은 뒤에야 키를 저장한다면, 그 사이에 장애가 나면 어떤 키를 사용했는지 애플리케이션이 알 수 없게 될 수 있습니다.
의도와 키를 먼저 저장해 두면 복구가 쉬워집니다.
멱등성과 중복 제거는 같은 것인가요?
서로 관련은 있지만 같지는 않습니다.
중복 제거는 반복된 이벤트를 식별해 두 번 이상 처리하지 않도록 하는 것입니다.
멱등성은 작업을 반복해도 추가 효과가 생기지 않도록 보장하는 것입니다.
시스템이 event_id로 중복을 제거하더라도 외부 호출에는 여전히 멱등성이 필요할 수 있습니다.
exactly-once 전달은 어떤가요?
실제로 분산 시스템이 종단 간 물리적으로 정확히 한 번 전달되는 것에 의존할 수 있는 경우는 드뭅니다.
큐와 네트워크는 재전송을 동반한 at-least-once 전달을 우선하는 경향이 있습니다.
그래서 멱등한 컨슈머가 중요합니다.
목표는 메시지가 여러 번 도착하더라도 비즈니스 효과를 한 번만 얻는 것입니다.
HTTP GET은 원래 멱등한가요?
HTTP 의미론에 따르면 GET은 의미 있는 비즈니스 효과가 없는 조회여야 합니다.
하지만 잘못 설계된 API는 이 원칙을 어길 수 있습니다.
결제에서 멱등성은 주로 생성, 매입, 취소, 환불 같은 명령과 관련이 있습니다.
PUT은 멱등한가요?
PUT이 알려진 리소스의 상태를 대체하거나 설정할 때 HTTP 의미론상 멱등합니다.
그렇더라도 실제 동작은 구현에 달려 있습니다.
HTTP 메서드만 보고 금전적 안전성을 가정해서는 안 됩니다.
POST도 멱등할 수 있나요?
네.
많은 결제 API가 멱등성 키와 함께 POST를 사용해 생성과 명령을 안전하게 반복할 수 있도록 합니다.
메서드만으로는 보장이 정의되지 않습니다.
서버가 파라미터를 비교해야 하나요?
이상적으로는 그렇습니다.
같은 키가 다른 금액이나 페이로드와 함께 들어온다면 클라이언트에 버그가 있을 가능성이 큽니다.
일부 API는 파라미터가 첫 요청과 일치하지 않으면 키 재사용을 거부합니다.
이렇게 하면 키가 서로 다른 의도를 위한 범용 식별자가 되는 것을 막을 수 있습니다.
키는 얼마나 오래 기억해야 하나요?
공급자의 계약과 여러분의 시스템에 따라 다릅니다.
일부 서비스는 정해진 기간 동안 결과를 보관합니다. 그 이후에는 키를 재사용하면 새로운 작업으로 처리될 수 있습니다.
애플리케이션은 이 기간을 알고 있어야 하며, 영구적인 보장이 없다면 이에 의존해서는 안 됩니다.
로컬 멱등성은 PSP보다 오래 유지해야 하나요?
좋은 전략이 될 수 있습니다.
공급자가 일정 기간 후 키를 잊더라도, 여러분의 시스템은 의도를 보관하고 위험한 뒤늦은 반복을 막을 수 있습니다.
내부 규칙이 외부 보관 기간에 묶일 필요는 없습니다.
타임아웃이 나면 어떻게 되나요?
타임아웃은 전형적인 사례입니다.
애플리케이션은 요청을 보냈지만 PSP가 처리했는지 알 수 없습니다. 새 키를 생성하는 대신, 계약이 허용하는 경우 같은 키로 같은 의도를 반복해야 합니다.
그러면 첫 호출이 이미 효과를 냈더라도 서버가 반복임을 알아볼 수 있습니다.
멱등성이 알 수 없는 결과를 없애주나요?
항상 그렇지는 않습니다.
중복 위험은 줄여 주지만, 최종 결과를 알기 위해 애플리케이션이 리소스를 조회해야 할 수도 있습니다.
멱등성 키는 안전한 반복을 위한 장치이지 상태 머신을 대신하는 것이 아닙니다.
멱등성이 서로 다른 PSP 사이의 이중 청구를 막아주나요?
자동으로 막아주지는 않습니다.
한 PSP의 키는 보통 다른 PSP에게 아무 의미가 없습니다.
PSP A에서 타임아웃을 받고 PSP B로 새 시도를 보내면 효과가 두 번 생길 수 있습니다.
플랫폼은 결제와 시도 수준에서 이를 통제해야 합니다.
여러 PSP를 쓸 때 멱등성은 어떻게 모델링하나요?
의도에는 내부 식별자를, 각 시도에는 외부 식별자를 사용합니다.
결제는 구매를 나타낼 수 있습니다. 시도는 하나의 PSP에 대한 호출을 나타냅니다. 시도의 각 명령은 해당 공급자에서 고유한 멱등성 키를 가집니다.
새로운 시도를 언제 만들 수 있는지는 상태 머신이 결정합니다.
승인과 매입에 같은 키를 써도 되나요?
보통은 안 됩니다.
둘은 서로 다른 명령이며 페이로드, 엔드포인트, 효과가 다를 수 있습니다.
금전적 의도마다 고유한 식별자가 있어야 합니다.
부분 환불은 어떤가요?
환불마다 고유한 식별자가 있어야 합니다.
하나의 구매에 대해 서로 다른 시점에 50헤알짜리 정당한 환불이 두 번 이루어진다면, 같은 멱등성 키를 공유할 수 없습니다.
반면 첫 번째 환불을 재시도할 때는 그 환불의 키를 재사용해야 합니다.
프런트엔드의 중복 클릭은 어떻게 막나요?
버튼을 비활성화하면 UX에는 도움이 되지만 보장은 되지 않습니다.
사용자가 탭 두 개를 열 수도 있고, 네트워크가 요청을 반복할 수도 있으며, 공격자가 API를 직접 호출할 수도 있습니다.
진짜 보호 장치는 백엔드에 있어야 합니다.
브라우저에서 키를 생성해도 되나요?
백엔드가 키를 검증하고 세션이나 의도에 올바르게 연결한다면 가능합니다.
많은 아키텍처는 범위를 통제하기 위해 서버에서 키를 생성하거나 확인하는 방식을 선호합니다.
중요한 것은 인터페이스 동작에만 의존하지 않는 것입니다.
멱등한 의도는 어떻게 저장하나요?
키, 작업 유형, 관련 페이로드, 상태, 결과, 타임스탬프를 담은 레코드를 만듭니다.
같은 키가 들어오면 애플리케이션은 이 레코드를 조회합니다.
작업이 끝났다면 해당 결과를 반환합니다. 진행 중이라면 기다리거나 중간 상태를 반환할 수 있습니다.
같은 키를 가진 요청 두 개가 동시에 오면 어떻게 되나요?
중요한 테스트 항목입니다.
시스템은 상호 배제나 유일성 제약을 보장해 하나의 실행만 성공하도록 해야 합니다.
동시성 제어가 없으면 두 스레드가 동시에 '없음'을 확인하고 청구를 두 번 실행할 수 있습니다.
유일성 제약으로 해결되나요?
큰 도움이 됩니다.
데이터베이스에서 키의 범위에 유일성 제약을 걸면 같은 의도에 대해 행이 두 개 생기는 것을 막을 수 있습니다.
하지만 외부 호출을 언제 할지, 장애 후 어떻게 복구할지는 여전히 조율해야 합니다.
check-then-act의 문제는 무엇인가요?
'존재하는지 확인하고, 없으면 생성한다'는 패턴입니다.
동시성 상황에서는 둘 중 하나가 레코드를 만들기 전에 두 프로세스가 모두 확인을 통과할 수 있습니다.
이 결정은 원자적으로 이루어지거나 제약 또는 락으로 보호되어야 합니다.
Outbox 패턴은 어떻게 도움이 되나요?
애플리케이션은 상태 변경과 발신 메시지를 같은 트랜잭션 안에서 저장할 수 있습니다.
그다음 워커가 메시지를 PSP나 다른 서비스로 전달합니다.
이렇게 하면 데이터베이스에는 의도가 기록됐는데 명령을 발행하기 전에 프로세스가 죽는 상황을 피할 수 있습니다.
Inbox 패턴은요?
컨슈머가 처리한 메시지의 ID를 저장해 중복 전달을 걸러냅니다.
웹훅과 큐에 유용합니다.
Outbox와 Inbox는 흐름의 서로 다른 부분을 해결하며, API 멱등성과 잘 어울립니다.
멱등성은 오류를 반환해야 하나요, 이전 결과를 반환해야 하나요?
계약에 따라 다릅니다.
반복 요청이 정확히 같은 의도라면 이전 결과를 반환하는 것이 편리합니다.
같은 키가 다른 파라미터와 함께 들어오면 거부하는 편이 더 안전합니다.
전체 응답을 저장해야 하나요?
유용할 수 있지만 크기, 민감한 데이터, 스키마 변화를 고려해야 합니다.
생성된 리소스에 대한 참조를 저장하고 현재 응답을 다시 구성하는 방법도 있습니다.
선택은 제공하려는 계약에 따라 달라집니다.
오류를 멱등한 결과로 저장해도 되나요?
일부 공급자는 실행이 시작된 뒤 발생한 오류에 대해 그렇게 합니다.
논리는 타당합니다. 작업이 실제로 시작되어 특정 오류로 끝났다면, 반복이 조용히 새로운 실행을 만들어서는 안 됩니다.
다만 실행 전의 검증 오류는 다르게 처리될 수 있습니다.
재시도 가능한 오류와 그렇지 않은 오류는 어떻게 구분하나요?
분류할 때는 의미를 고려해야 합니다.
작업이 멱등하다면 타임아웃과 5xx 오류는 재시도할 수 있습니다. 검증 오류는 보통 페이로드를 수정해야 합니다. 카드 거절은 무작정 반복해서는 안 됩니다.
HTTP 상태 코드는 판단의 일부일 뿐입니다.
500 응답은 재시도해야 하나요?
자동으로 해서는 안 됩니다.
먼저 PSP의 계약, 멱등성, 그리고 결과를 알 수 없는 상태인지 확인하세요.
일부 공급자는 결과가 500이었더라도 멱등한 결과로 저장합니다.
애플리케이션은 해당 문서를 따라야 합니다.
429는요?
요청 한도 초과에는 보통 백오프를 동반한 재시도가 필요합니다.
그래도 명령 자체는 멱등해야 합니다.
공급자가 처리 전에 거부했다면 재시도가 안전할 수 있지만, 동작이 불분명하다면 문서에 명시된 보장을 따라야 합니다.
지수 백오프란 무엇인가요?
재시도 사이의 간격을 점점 늘리는 것입니다.
장애가 발생했을 때 부하를 줄여 줍니다.
지터는 변동을 추가해 수천 개의 클라이언트가 같은 순간에 재시도하지 않도록 합니다.
백오프가 멱등성을 대신할 수 있나요?
아니요.
재시도 간격을 벌릴 뿐입니다.
반복할 때마다 새로운 효과가 생긴다면, 중복이 더 천천히 생길 뿐입니다.
웹훅에도 멱등성이 필요한가요?
컨슈머는 멱등해야 합니다.
같은 웹훅이 여러 번 도착할 수 있습니다.
같은 event_id를 다시 처리해도 상태 변경, 잔액, 주문 이행이 중복되어서는 안 됩니다.
웹훅 중복은 어떻게 제거하나요?
이벤트의 고유 식별자나 신뢰할 수 있는 파생 키를 저장하고 유일성 제약을 사용합니다.
그런 다음 상태 전이를 안전하게 처리합니다.
공급자가 event_id를 제공하지 않는다면 객체 식별자에 버전이나 상태를 조합해 신중하게 사용해야 할 수도 있습니다.
이벤트 순서와 멱등성은 같은 문제인가요?
아닙니다.
멱등성은 중복을 막고, 순서는 상태가 뒤로 돌아가는 것을 막습니다.
오래된 이벤트가 고유하더라도 더 최근 이벤트보다 늦게 도착할 수 있습니다.
상태 머신이 전이를 검증해야 합니다.
멱등성과 원장(ledger)은 어떤 관계인가요?
금전적 이벤트마다 분개는 한 번만 생성되어야 합니다.
매입 웹훅이 두 번 도착해도 원장의 제약이 두 번의 입금 기록을 막아 줍니다.
분개의 출처 키는 멱등성의 한 형태입니다.
멱등성과 대사(reconciliation)는 어떤 관계인가요?
대사는 보호 장치가 실패했거나 외부 이벤트가 예상과 다를 때 이를 찾아냅니다.
멱등성이 있어도 버그는 생길 수 있습니다.
대사는 두 번째 방어선입니다.
리소스 기반 멱등성이란 무엇인가요?
임의의 키 대신 알려진 리소스를 사용하는 작업입니다.
예를 들어 '청구 X의 상태를 취소됨으로 설정'은 최종 결과가 같다면 본질적으로 반복 가능합니다.
하지만 새 객체를 생성하는 금전적 명령에는 보통 명시적인 키가 필요합니다.
키의 범위는 어떻게 정하나요?
키는 전역, 가맹점별, 엔드포인트별, 리소스별로 정할 수 있습니다.
범위는 정당한 작업끼리 충돌하지 않도록 정해야 합니다.
범위에 merchant_id가 포함된다면 서로 다른 두 가맹점이 같은 키 '123'을 써도 허용될 수 있습니다.
멱등성 키 충돌이란 무엇인가요?
서로 다른 두 의도가 같은 키를 받을 때 발생합니다.
서버가 파라미터를 비교하지 않으면, 한 작업이 다른 작업의 결과를 받게 될 수 있습니다.
엔트로피가 높은 무작위 생성기는 우발적 위험을 줄이지만, 애플리케이션은 논리적 재사용도 통제해야 합니다.
재시도는 어떻게 감사하나요?
attempt_id, 멱등성 키, HTTP 시도 번호, 타임스탬프, 결과, 그리고 가능하다면 공급자의 요청 ID를 기록합니다.
이렇게 하면 몇 번의 호출이 있었는지를, 몇 번의 금전적 효과가 있었는지와 혼동하지 않고 파악할 수 있습니다.
고객 지원팀이 재시도 횟수를 봐야 하나요?
장애를 조사할 때 유용할 수 있습니다.
지원팀이 프로토콜의 세부 사항까지 알 필요는 없지만, 타임아웃과 멱등한 복구가 있었다는 사실을 알면 고객에게 다시 결제하라고 요청하지 않고도 지연을 설명할 수 있습니다.
멱등성은 어떻게 테스트하나요?
같은 요청을 병렬로 여러 번 보냅니다.
의도를 저장한 뒤 외부 호출 전에 강제로 장애를 일으킵니다. PSP가 처리한 뒤에 타임아웃을 일으킵니다. 웹훅을 다시 보냅니다. 큐를 다시 처리합니다.
시스템은 하나의 효과로 수렴해야 합니다.
페이로드 변경은 어떻게 테스트하나요?
같은 키로 다른 금액을 보내 API가 거부하는지 확인합니다.
이 시나리오는 키를 잘못 재활용하는 클라이언트의 버그를 잡아냅니다.
키 만료는 어떻게 테스트하나요?
공급자 문서에 나온 기간이 지난 뒤 반복하는 상황을 시뮬레이션합니다.
내부 애플리케이션은 작업을 계속 막을지, 아니면 명시적으로 새로운 의도를 만들지를 결정해야 합니다.
멱등성은 공개 API에 드러나야 하나요?
외부 클라이언트가 효과를 일으키는 작업을 수행한다면 그렇습니다.
결제 API는 안전한 재시도를 위한 명확한 장치를 제공해야 합니다.
멱등성을 SDK 안에만 숨겨 두면 직접 연동하는 경우를 다루지 못합니다.
헤더와 본문 필드 중 어디에 두나요?
둘 다 가능합니다.
키는 비즈니스 리소스가 아니라 요청의 의미에 속하기 때문에 헤더가 흔히 쓰입니다.
가장 중요한 것은 일관된 계약입니다.
멱등성은 어떻게 문서화하나요?
어떤 엔드포인트가 지원하는지, 키의 범위, 보관 기간, 페이로드가 다를 때의 동작, 동시성, 오류 유형을 설명합니다.
모호한 문서는 클라이언트가 위험한 가정을 하게 만듭니다.
멱등성이 단 한 번의 청구를 보장하나요?
구현된 범위 안에서 안전한 반복을 보장합니다.
애플리케이션이 서로 다른 키로 두 개의 의도를 만든다면, 기술적으로 정당한 청구가 두 건 생깁니다.
그래서 비즈니스 식별자도 통제해야 합니다.
payment_id와 idempotency_key의 차이는 무엇인가요?
payment_id는 객체를 식별합니다.
멱등성 키는 명령의 의도를 식별합니다.
하나의 결제는 수명 주기 동안 여러 개의 멱등한 명령을 받을 수 있습니다.
다른 엔드포인트에서 키를 재사용해도 되나요?
보통은 좋은 생각이 아닙니다.
범위는 공급자마다 다르며, 재사용은 충돌을 일으킬 수 있습니다.
키는 하나의 특정 작업을 나타내야 합니다.
멱등성은 AI 에이전트에게 어떻게 도움이 되나요?
에이전트는 실패 후 계획을 다시 세우고 행동을 반복할 수 있습니다.
멱등성이 없으면, 확인을 받지 못한 자동화가 같은 결제를 여러 번 실행할 수 있습니다.
돈을 움직이는 자율적 계층에는 안전하게 반복할 수 있는 작업이 필요합니다.
이런 에이전트가 구매하는 맥락을 이해하려면 에이전틱 커머스(Agentic Commerce)란? 쇼핑몰 준비 가이드를 읽어 보세요.
멱등성은 기존 자동화에 어떻게 도움이 되나요?
스케줄러, 큐, 잡도 반복 실행됩니다.
원칙은 같습니다. 인프라는 메시지가 두 번 이상 도착할 수 있다고 가정해야 합니다.
PSP 응답 후 데이터베이스가 다운되면 어떻게 되나요?
까다로운 시나리오입니다.
PSP에서는 효과가 발생했지만, 애플리케이션은 결과를 저장하지 못했습니다.
멱등성 키를 미리 저장해 두었다면, 복구 과정에서 호출을 반복해 다른 효과나 리소스를 만드는 대신 같은 효과나 리소스를 얻을 수 있습니다.
키가 저장되지 않았다면요?
애플리케이션이 그 작업을 알아볼 능력을 잃을 수 있습니다.
그래서 외부 호출 전에 키를 생성하고 저장하는 것이 견고한 방법입니다.
멱등한 작업은 어떻게 대사하나요?
보장이 있더라도 조회와 대사 절차는 유지하세요.
이 절차들은 외부 리소스가 내부 기록과 일치하는지 확인합니다.
돈이 걸린 문제에서는 다층 방어가 중요합니다.
멱등성이 해결하지 못하는 것은 무엇인가요?
사기, 이벤트 순서, 잘못된 상태 전이, 잘못된 금액, 잘못된 라우팅, 서비스 중단은 해결하지 못합니다.
멱등성이 해결하는 것은 하나의 구체적인 문제, 즉 효과를 중복시키지 않고 같은 의도를 반복하는 것입니다.
안전한 재시도와 새로운 시도는 어떻게 다른가요?
안전한 재시도는 같은 식별자로 같은 의도를 반복하는 것입니다.
새로운 시도는 이전 시도가 알려진 결과로 끝났거나 정책이 진행하기로 결정했기 때문에 새로운 실행을 만드는 것입니다.
둘을 혼동하는 것이 중복의 흔한 원인입니다.
멱등성은 API 금융 계약의 일부입니다
결제 API는 완벽한 네트워크를 가정할 수 없습니다.
연결은 끊기고, 클라이언트는 재시도하고, 큐는 재전송하며, 프로세스는 다시 시작됩니다.
올바른 설계는 반복을 예상된 동작으로 바꿉니다.
멱등성 키, 상태 머신, 제약, 대사가 함께 작동하면 플랫폼은 탄력성을 중복 청구로 바꾸지 않고도 장애에서 복구할 수 있습니다.