카페24 RateLimit

개요

2025.12.01 기준 카페24는 API에 두 가지 RateLimit 정책을 사용하고 있습니다. https://developers.cafe24.com/docs/ko/api/admin/#api-limit RateLimit 정책은 mallId에 별도로 적용됩니다. (RateLimit은 셀러별 독립적)

1. 요청 수 제한
2. 사용량 제한

요청 수 제한

최대 40번을 수용할 수 있는 버킷이 존재하고, 1초에 2번 회복되는 단순한 로직으로 구현되어 있습니다.

즉, 1초에 2회 호출이 가능하도록 RateLimiter를 설정할 수 있으며, 안정적인 운영을 위해 약간의 여유를 두어 0.6초당 1회 호출을 권장합니다.

이 제한은 API별로 개별 적용됩니다.

사용량 제한

호출 횟수, 처리 시간 한도 대비 사용률(100%)을 기반으로 구현되어 있습니다.

두 값 중 하나라도 사용량이 초과한 경우, HTTP 429 응답이 발생합니다.

이 제한은 특정 API에만 적용되는 것이 아니라, mallId별 전체 API를 대상으로 적용됩니다.

따라서 해당 제한이 걸리게 되면, 상품 재고 연동과 같은 매우 중요한 기능이 마비되어, 중복 주문이 발생할 수 있습니다.

사용량 제한으로 인한 문제 상황

상품 게시의 경우 총 5개의 API를 호출합니다.

1. 상품 생성
2. 상세 이미지 업로드
3. 추가 이미지 업로드
4. 본문 업데이트 (2, 3에서 얻은 이미지 경로)
5. 재고 업데이트

해당 API를 호출하면, 처리 시간 사용량 0.35% 정도를 사용합니다.

따라서 한 번에 약 280개 정도의 상품을 게시할 수 있는데, 그 이후에는 100%를 초과하게 되어 상품 게시에 실패하게 됩니다.

트랜잭션이 적용되는 RDB에서는 실패하면 롤백을 할 수 있지만, 외부 API 경우 그렇지 않기 때문에 정합성에 문제가 생긴 상품이 게시됩니다.

또한 상품은 게시됐지만, PublishedProduct는 올바르게 설정되지 않아, 재고 연동이 되지 않는 치명적인 문제와 재시도 시 중복된 상품이 게시되는 문제가 발생합니다.

더 치명적인 문제는 API 사용량이 초과해, 재고 연동 웹훅이 들어오더라도 처리가 불가능해지는 상황이 발생합니다.

일부 셀러의 경우, 한 번에 상품을 500개 넘게 게시하는 경우가 있기에, 사용량 제한을 지키며, 상품을 게시해야 합니다.

해결 - ApiUsageLimiter

결국 사용량이 100%가 되면, 시스템이 마비되기 때문에 절대로 사용량을 100% 초과하게 두어서는 안 됩니다.

따라서 카페24가 아닌, 어플리케이션 레벨에서 사용량 제한이 필요합니다.

또한 사용량을 대부분 차지하는 것은 상품 게시이므로, 상품 게시 로직에만 사용량 제한을 걸어두면 됩니다.

해당 로직은 Cafe24ApiUsageLimiterManager에 구현되어 있으며, 최대 사용량은 5000으로 설정되어 있습니다. 이는 API 사용량이 0.01 단위로 계산되는 점을 고려하여 100을 곱한 값입니다.

따라서 사용량이 적용된 로직을 호출하면, 사용량이 줄어들게 되며, 최종적으로 0 또는 음수가 되면, canCall에서 false가 반환되어, 예외를 던지게 되어있습니다.

또한 사용량은 분마다 100씩 회복되며, Cafe24 API 사용량 제한이 초기화되면, 사용량 또한 다시 5000으로 초기화됩니다.

즉, 사용량이 꽉 차면 쓰로틀링이 걸리게 되며, 쓰로틀링이 걸린 뒤, Cafe24 API의 사용량이 초기화되면 쓰로틀링이 풀리는 구조로 되어 있습니다.

사용량 제한이 걸렸을 시, 바로 실패하는 것은 사용자 경험에 부정적인 영향을 미치고, 일정 시간 뒤 재시도하면 반드시 성공이 보장되기에 Retry 로직 또한 구현되어 있습니다.

내결함성이 적용된 최종 코드의 흐름 순서는 다음과 같습니다.

Retry -> CircuitBreaker -> ApiUsageLimiter -> RateLimiter -> 비즈니스 로직