효과적인 API 재시도 로직 구현

API 재시도 로직이 중요한 이유

외부 서비스의 경우 네트워크 지연, 과부하 또는 유지보수로 인해 간헐적인 문제를 겪을 수 있음

이 때 재시도 로직이 없으면 단 하나의 일시적인 오류로 인해 모든 과정이 실패 처리됨

PCI-DSS 및 GDPR 같은 규정은 시스템 가용성과 데이터 무결성을 강조

강력한 재시도 메커니즘은 실패율을 줄여 이러한 표준을 충족하는데 도움이 됨

 

 

 

 

 

재시도를 해야하는 일반적인 일시적 문제

- 네트워크 타임아웃 또는 연결 오류

- HTTP 5xx 서버 오류

- HTTP 429 너무 많은 요청 (속도 제한)

- 일시적인 서비스 이용 불가를 나타내는 특정 공급업체 코드

 

 

 

 

재시도를 피해야하는 영구적인 문제

- HTTP 4xx 클라이언트 오류

 

 

 

 

안전한 재시도를 위한 지수 백오프 구현

지연 = 초기 간격 * (승수 ^ (시도 횟수 - 1))

 

동시 재시도를 방지하기 위해 지터(임의의 변화)를 추가해야함

 

 

 

 

 

API 재시도와 멱등성

재시도는 결제 생성과 같은 POST 요청처럼 멱등성이 없는 작업에서 중복 위험을 초래

 

명등성 키 (idenpoency key)는 이를 방지

 

클라이언트는 헤더에 고유한 키 (예: UUID)를 보내고 

서버는 응답을 캐시하고 중복 키에 대해 생성을 다시 실행하지 않고 캐시된 응답을 반환

 

- 멱등성 구현

논리 작업당 클라이언트 측 키 생성

만료기간을 두고 서버 측에 저장

일치하는 경우 캐시된 결과 반환

 

 

 

 

 

API 재시도와 서킷 브레이커

재시도는 일시적인 실패를 처리하지만, 지속적인 문제는 에스컬레이션이 필요

 

서킷 브레이커는 실패율을 모니터링

임계 값 (예: 10개 요청 중 50% 실패)을 초과하면 브레이커가 "열리고" 이후 호출은 즉시 실패

 

- 상태

닫힘 (Closed): 모니터링과 함께 정상 작동

열림 (Open): 즉시 실패, 선택적으로 폴백(fallback)

반열림 (Half-Open): 제한된 요청으로 복구 테스트

 

- 관련 라이브러리

Hystrix (레거시)

Resilience4j

Polly

 

 

 

 

 

API 재시도와 속도 제한

HTTP 429를 응답을 통해 Retry-After 헤더를 클라이언트가 확인

 

- 스마트 재시도 로직

429 응답 시 백오프

사용량 윈도우 추적

클라이언트 측 스로틀링 구현

 

 

 

 

API 재시도 로직 테스트

- 오류 시뮬레이션 (5xx, 429, 타임아웃)을 위한 목(Mock) 서버 사용

- 시나리오 자동화: N번째 재시도 시 성공, 영구 실패

- 멱등성 검증: 중복 요청이 단일 효과를 가져오는지 확인

- 시스템 복원력 확인을 위한 실패를 포함한 부하 테스트

 

 

 

 

 

 

Reference

https://apidog.com/kr/blog/fintech-api-retry-logic/

효과적인 핀테크 API 재시도 로직 구현 방법: 성공 전략 및 모범 사례