멱등성과 재시도

[koreaioi]

멱등성을 전제로 하는 재시도는 언제, 어떤 기준으로 적용해야 할까요?

• 재시도 정책(횟수/간격)
• 멱등성 적용 기준
• 관련 예외 처리

이번 외부 API 미션에서 Toss 결제 승인 API를 사용할 때, 멱등성 키(Idempotency-Key)로 안전하게 재시도를 보장하라는 문구가 있습니다.
위 내용 말고도 해당 내용에 대해서 자유롭게 이야기 해주셔도 됩니다.
(멱등성에 관하여 하고싶은말)

[softmoca]

저는 멱등성을 '같은 작업이 여러 번 실행되더라도 시스템 상태를 한 번 실행한 것과 동일하게 유지하는 설계 원칙'이라고 생각합니다.

같은 작업이 중복 실행되는 상황은 생각보다 많습니다.
사용자가 결제 버튼을 두 번 누를 수도 있고, 외부 API의 응답이 유실돼 클라이언트가 재시도할 수도 있습니다.
Kafka처럼 최소 한 번 전달을 보장하는 메시지 시스템에서는 같은 메시지가 여러 번 전달될 수 있고,
Outbox 이벤트 발행이나 배치 작업, 데드락으로 롤백된 트랜잭션도 다시 실행될 수 있습니다.

이런 상황에서 중요한 것은 단순히 같은 응답을 반환하는 것이 아니라,
요청을 여러 번 실행해도 시스템의 최종 상태가 한 번 실행했을 때와 같아야 한다는 것입니다.
예를 들어 결제 승인 요청이 두 번 들어왔을 때 응답 메시지만 같고 실제 결제가 두 번 처리됐다면 멱등하다고 볼 수 없습니다.
실제 결제 상태 자체가 한 번만 처리된 것처럼 유지돼야 합니다.

멱등성을 보장하는 방법은 상황에 따라 다릅니다.
외부 결제 API에서는 보통 Idempotency-Key를 사용합니다.
클라이언트가 요청마다 고유한 키를 생성하고, 재시도할 때 같은 키를 사용하면 서버가 이미 처리한 요청인지 식별해서 중복 결제를 막고 기존 결과를 반환할 수 있습니다.

이 방식은 외부 API에만 적용되는 것은 아닙니다.
자체 결제 API에서도 사용자의 더블클릭에 대비해 클라이언트가 요청 ID를 보내고 서버가 해당 키의 처리 결과를 저장해 중복 요청을 막을 수 있습니다.

그 외에도 주문 번호 같은 비즈니스 키를 기준으로 중복을 검사하거나,
데이터베이스의 UNIQUE 제약 조건을 마지막 방어선으로 사용할 수 있습니다.
메시지 컨슈머라면 처리한 메시지 ID를 별도의 테이블에 기록하고,
이미 처리한 메시지가 다시 들어왔을 때 건너뛰는 방식도 사용할 수 있습니다.
상태를 특정 값으로 변경하는 UPDATE처럼 연산 자체를 멱등하게 설계하는 방법도 있습니다.

재시도는 이런 멱등성이 보장된 이후에 적용해야 안전합니다.
재시도할 때는 일반적으로 타임아웃이나 일시적인 네트워크 오류, 5xx 응답을 대상으로 하고, 400이나 401처럼 같은 요청을 다시 보내도 결과가 바뀌지 않는 오류는 즉시 실패 처리합니다.
또한 지수 백오프와 지터를 적용해 재시도 요청이 한꺼번에 몰리는 것을 막고, 재시도 횟수도 제한해야 합니다.
특히 타임아웃은 서버가 요청을 받지 못한 것인지, 처리는 완료했지만 응답만 유실된 것인지 클라이언트가 알 수 없습니다.
따라서 타임아웃은 재시도 대상이 될 수 있지만, 결제처럼 중복 실행이 위험한 작업이라면 반드시 멱등성 보장과 함께 사용해야 합니다.

결국 책임을 나눠보면, "요청을 받는 쪽은 멱등성을 통해 중복 실행을 흡수하고,
요청을 보내는 쪽은 재시도를 통해 일시적인 실패와 응답 유실을 복구해야 한다"고 생각합니다.
그래서 시스템을 설계할 때는 먼저 “이 작업이 두 번 실행될 가능성이 있는가?”를 확인하고,
가능성이 있다면 “중복 실행의 위험을 어느 계층에서 어떤 방식으로 흡수할 것인가?”를 결정해야 합니다.

정리하면 멱등성은 외부 API 호출에만 필요한 기술이 아니라, 사용자 요청, 메시지 처리, 이벤트 발행, 배치와 트랜잭션 재시도까지 분산 시스템 전반에서 '한 번 더 실행돼도 안전한 시스템을 만드는 원칙'입니다.

[Uechann]

멱등성

같은 요청을 몇 번 반복하더라도 결과가 항상 동일하다는 성질이다.
단순히 응답이 같은 것이 아니라, 서버 상태(데이터)까지 첫 요청과 동일해야 진짜 멱등하다고 할 수 있다.

• 결제 승인을 3번 보냈는데, 응답이 다 200이어도, 실제 3번이 결제됐다면 멱등하지 않다.
• 결제 승인을 3번 보냈는데, 실제 결제는 1번만 일어나고 나머지는 첫 응답을 그대로 돌려준다면 멱등하다.

네트워크는 언제든 끊길수가 있고, 클라이언트가 요청을 보냈는데 응답을 못 받으면 두 가지 상황의 가능성이 동시에 존재한다.

1. 서버가 처리하지 못해서 재시도를 해야함
2. 서버가 처리는 했지만, 응답만 유실 → 재시도한다면 이중 처리이다.

응답을 받지 못했다는 사실만으로 1,2인지 클라이언트는 구분하기 어렵다.

그래서 멱등성이 있다면, 1,2이든 신경 쓸 필요 없이 그냥 같은 멱등키로 재시도를 하고,
2번이라면 서버가 첫 결과를 그대로 돌려주고,
1번이었다면 정상 처리가 된다.

즉, 멱등성은 안심하고 재시도할 수 있는 권리를 제공해준다고 생각한다.
재시도 전략과 멱등성을 같이 생각해야 한다.

멱등키로 중복 식별

토스의 서버 기준, 멱등 요청의 식별은 다음 조합으로 한다.

멱등키(Idempotency-Key) + API 키 + API URL + HTTP 메서드

• 이 조합이 같다면 중복 요청으로 판단하고 첫 요청과 동일한 응답으로 반환한다.
• API 키, URL, 메서드가 다르다면 같은 멱등키여도 새 요청으로 받아들인다.

토스 블로그 기준 서버의 내부 의사 흐름

1. 요청에 멱등키가 있는지 확인
2. 멱등키 저장소 DB, Redis를 조회한다.
3. 같은 키 기록이 이미 있으면, 저장된 응답을 그대로 반환한다.
4. 없다면 실제 처리 후 응답을 멱등키와 함께 저장한다.
5. 저장 기간이 지나면 같은 키로 새로운 요청이 가능하도록 한다. (멱등키의 유효기간)

저장소가 단순 K-V이라면 Redis로, 복잡하다면 별도 DB/테이블을 권장한다고 한다.

재시도 정책과 예외 처리 구현

재시도 정책

항목	권장	이유
횟수	결제 같은 민감 작업 2~3회, 무한 재시도 금지	재시도가 길어지면 사용자 대기·부하 폭증
간격	지수 백오프 (예: 1s → 2s → 4s)	고정 간격은 회복 안 된 서버를 계속 때림
지터(jitter)	백오프에 무작위 흔들기 추가	다수 클라이언트 동시 재시도(thundering herd) 방지
타임아웃	connection / read 타임아웃 분리 설정	read 타임아웃 없으면 영원히 매달림
전체 데드라인	누적 재시도 시간 상한 설정	총 N초 안에 못 하면 포기 예산 관리

예외처리

재시도를 해야하는것: 일시적이고 결과가 불확실한 상황

• 연결 거부, 리셋, read 타임 아웃
  SocketTimeoutException, ResourceAccessException
• 5xx 에러
• 409 IDEMPOTENT_REQUEST_PROCESSING 첫 요청이 아직 처리중

재시도 안해도 되는것: 영구적으로 결과가 정해진 상황

• 4xx 에러
• 비즈니스의 거절: 잔액 부족, 카드 한도 초과, 한도 정책 위반

Spring에서 재시도 구현

• 멱등키는 요청 진입점에서 1회 생성해서 변수/DB에 보관하고,
  HTTP 클라이언트 호출과 재시도에서 동일한 키를 사용한다.
• 재시도는 직접 루프보다 Resilience4j Retry 또는 Spring Retry로 분리한다.
  • @retryable에서
    retryOn / retryExceptions에 재시도가 가능한 예외만 등록하고,
    비즈니스 거절을 noRetryOn으로 처리한다.
  • 백오프 설정에 multiplier 지수 와 randomized 지터를 적용시킨다.
• HTTP 상태별로 분리를 처리한다.
  • 5xx/타임아웃은 재시도로 신호로 변환하고,
  • 4xx 에러는 즉시 실패 예외로 변환하는 에러 핸들러를 둔다.

[sangjun121]

멱등성을 전제로 하는 재시도는 “같은 요청을 여러 번 보내도 결과가 한 번 처리된 것과 같을 때”만 적용해야 한다고 생각합니다. 특히 외부 API 호출에서는 네트워크 타임아웃, 일시적인 5xx 서버 오류, 연결 실패처럼 실제 처리 결과를 우리 서버가 확신할 수 없는 경우에 재시도가 필요하기에 멱등성을 보장해야합니다.

재시도 횟수

재시도 정책은 무한 재시도가 아니라 제한적으로 가져가야 한다고 생각합니다. 예를 들어 최대 3회 정도만 재시도하고, 간격은 1초에서 2초, 2초에서 4초처럼 점진적으로 늘리는 방식이 적절할것 같습니다. 이렇게 해야 일시적인 장애는 복구할 수 있으면서도, 외부 API나 우리 서버에 과도한 부하를 주지 않을 수 있다고 생각합니다.

언제 사용할지

멱등성 적용 기준은 “중복 처리되면 치명적인 작업인가?”라고 생각합니다. 결제 승인, 결제 취소, 주문 생성, 포인트 충전처럼 한 번만 실행되어야 하는 작업에는 반드시 멱등성을 고려할 필요가 있습니다.

멱등성 예외처리

400, 401, 403처럼 요청 값이나 인증이 잘못된 경우는 재시도해도 성공 가능성이 낮으므로 즉시 실패 처리하는 것이 적절하고, 500번대 오류, 타임아웃, 네트워크 연결 실패는 일시적인 문제일 수 있으므로 멱등성 키가 있다는 전제하에 제한적으로 재시도할 필요가 있다고 생각합니다.

결국 멱등성은 “무조건 재시도해도 된다”는 의미가 아니라, “재시도해도 중복 부작용이 생기지 않도록 설계한다”는 의미에 더 부합한다 생각합니다. 결제 같은 도메인에서는 외부 API 호출 성공 여부와 우리 서버의 후속 처리 성패 여부가 어긋날 수 있기 때문에, 결제 승인 자체뿐 아니라 DB 저장, 주문 상태 변경, 포인트 지급 같은 내부 처리도 함께 멱등하게 설계해야 무결성이 보장됩니다. 예를 들어 orderId나 paymentKey에 unique 제약을 걸고, 이미 처리된 결제라면 에러로만 보지 않고 이미 성공한 요청으로 해석해야합니다.

[haeyoon1]

멱등성을 전제로 한 재시도는 같은 요청을 다시 보내도 결과가 중복으로 발생하지 않을 때 적용해야 합니다.

주로 재시도할 수 있는 경우는 네트워크 timeout, 연결 실패, 일시적인 5xx 오류, 429, 처리 중 상태 같은 일시적 실패입니다.
반대로 파라미터 오류, 인증 실패, 금액 불일치, 카드 거절 같은 명확한 비즈니스 실패는 재시도 대상이 아닙니다.

찾아보니 재시도 정책은 보통 무한히 하지 않고, 최대 3회 정도로 제한하며 1초, 2초, 4초처럼 간격을 점점 늘리는 방식이 좋다고 합니다!

Toss 결제 승인 API처럼 중복 처리가 위험한 경우에는 같은 결제 승인 시도에 대해 같은 Idempotency-Key를 사용해야 합니다.
timeout이 발생했다고 새 키를 만들어 다시 요청하면 중복 처리 위험이 생길 수 있습니다.
따라서 멱등성 키는 주문이나 결제 요청 단위로 생성하고 DB에 저장해두는 것이 안전합니다.