스마트 스토어의 동적 API 호출 허용량 제한 방법 - 토큰 버킷 알고리즘

🚩개요

사내 ERP 서비스에 여러 쇼핑몰 기능을 연동하는 개선 작업을 진행하던 중, 한 가지 특이한 점을 발견했습니다. 여러 쇼핑몰 가운데에서도 네이버의 스마트스토어 연동에서만 유독 실패 응답이 빈번하게 발생하고 있었습니다.
응답 메시지는 대부분 동일했습니다.

“할당된 시간당 요청량을 초과하였습니다.”

 

저희 서비스에서는 이러한 실패 건을 단순 오류로 처리하고, 사용자에게 “잠시 후 다시 시도해 달라”는 안내만 제공하고 있었습니다.

저는 실패 빈도가 반복적으로 발생하는 점이 단순한 일시적 장애로 보기에는 이상하다는 생각이 들었습니다.

 

원인을 추적해본 결과, 문제는 서버 장애가 아니라 호출 방식 자체에 있었습니다.
네이버의 스마트스토어는 API 호출 허용량을 동적으로 제한하고 있었지만, 저희 시스템은 해당 제한을 고려하지 않은 채 요청을 지속적으로 전송하고 있었습니다. 그 결과 스마트스토어 서버 측에서는 정상적인 방어 로직에 따라 429(Too Many Requests) 응답을 반환했고, 저희 서비스는 이를 실패로 처리할 수밖에 없었던 것입니다.

 

해결 방법은 의외로 단순했습니다.
스마트스토어 API 호출 시 제공되는 호출 허용량 정보를 기준으로, 남은 호출 가능 횟수가 없을 경우 요청을 잠시 대기(sleep)시킨 뒤 다음 시간 구간에 다시 요청하도록 흐름을 조정했습니다. 이 개선만으로도 이전까지 빈번하게 발생하던 API 호출 실패가 거의 모두 사라졌고, 사용자 경험 역시 눈에 띄게 안정화되었습니다.

 

 

이번 작업을 통해 저는 네이버 스마트스토어가 '토큰 버킷 알고리즘(Token Bucket Rate Limiting Algorithm)' 을 기반으로 한 동적 API 호출 허용량 제한 방식에 주목하게 되었습니다. 이런 기능은 단순한 “제한 정책”이 아니라, Open API를 제공하는 플랫폼이 다수의 클라이언트로부터 서버를 보호하기 위한 매우 현실적이고 검증된 설계라는 점을 느꼈습니다.

 

 

그래서 이번 글에서는 네이버 스마트스토어의 동적 API 호출 허용량 제한 방식을 살펴보면서, 토큰 버킷 알고리즘이 무엇인지, 그리고 만약 내가 이 기능을 구현하는 입장이라면 어떻게 설계하고 구현할 것인지를 중심으로 정리해보고자 합니다.

 

 

 

동적 호출 허용량 제한”이 필요해진 이유

API를 운영하는 입장에서 가장 무서운 순간은 두 가지입니다.

• 예상 가능한 폭주
  예: 오전 10시 이후 주문이 급증, 발주 마감 시간, 대규모 프로모션, 명절 시즌 등.
  
  
• 예상 불가능한 폭주
  예: 특정 솔루션 버그로 무한 재시도, 장애 상황에서 재시도 폭발(thundering herd), 배치 작업이 한 시각에 동시에 실행.

이때 서버는 단순히 “CPU가 바쁘다” 수준이 아니라, DB 커넥션 풀 고갈, 스레드/이벤트루프 잠식, 캐시 미스 증가, 큐 과부화, 타임아웃 연쇄로 이어집니다. 더 위험한 건, 폭주가 한 사용자(또는 한 솔루션)에서 시작해도 결과는 플랫폼 전체 사용자에게 확산된다는 점입니다. 그래서 플랫폼은 “정상 사용자 보호”를 위해서라도 강제적인 제한 장치가 필요합니다.

 

또한 여기서 중요한 현실이 하나 있습니다. API는 “평균 처리량”만으로는 안전하지 않습니다. 실제 장애는 “순간 피크(버스트)”와 “연속된 재시도”에서 발생합니다.
즉, 플랫폼은 평균적으로는 충분히 처리 가능해도, “1초 사이에 몰리는 요청”을 제어해야 합니다.

이 문제를 풀기 위한 대표적인 방법이 토큰 버킷 알고리즘입니다.

 

 

 

 

🪣토큰 버킷 알고리즘

토큰 버킷은 네트워크 트래픽 제어 분야에서 수십 년간 사용돼 온 Rate Limiting 알고리즘입니다.

• 등장 배경: 네트워크 QoS(Quality of Service), 트래픽 쉐이핑
• 목적: 평균 처리율은 제한하면서, 순간적인 burst는 허용
• 사용 분야:라우터 / 스위치 트래픽 제어, OS 네트워크 스택, API Gateway / Reverse Proxy

 

토큰 버킷(Token Bucket)의 어원을 보면 버킷(bucket)은 토큰을 담아두는 저장 공간이고, 토큰(token)은 요청 1건을 처리할 수 있는 권한을 말합니다. 

 

동작 원리는 매우 단순합니다.

1. 버킷에 토큰이 일정 속도로 채워짐 (예: 초당 10개)
2. 요청 1개당 토큰 1개 소비
3. 토큰이 없으면 요청 거절 (429)
4. 다음 토큰 수만큼 가불해서 사용 가능 → burst 허용(대신 연속적으로 사용은 불가)

 

토큰 버킷(Token Bucket) 알고리즘이 “API 호출 제한”에 잘 맞는 이유는 다음과 같습니다.

 

(1) 초당 처리량을 명확하게 “정의”할 수 있다.
토큰이 초당 N개 채워지면, 시스템은 초당 N개 수준으로 요청을 안정적으로 처리하게 됩니다. 서버 입장에서는 리소스 사용량 상한선을 만들 수 있습니다.

(2) 짧은 버스트를 “유연하게” 받아줄 수 있다.
현실 트래픽은 일정하지 않습니다. 토큰이 쌓여 있다면 순간적으로 몇 개 더 처리해도 전체 안정성에 큰 문제가 없습니다. 이런 “짧은 급증”을 허용하면 클라이언트 체감 성능도 좋아집니다.

(3) 거절(HTTP 429)을 “정책적으로” 일관되게 만들 수 있다.
"이 API에 당신의 토큰이 없으면 거절". 이유가 명확합니다.
이 일관성이 클라이언트에게도 중요합니다. 애매하게 타임아웃으로 죽는 것보다, “너 지금 너무 많이 보냈다(429)”가 훨씬 설계하기 쉽습니다.

스마트 스토어의 커머스API 플랫폼은 바로 이 토큰 버킷 기반으로 호출량을 통제합니다.

 

 

 

🚀스마트 스토어의 동적 API 호출 허용량 제한 방법

스마트 스토어 커머스API 플랫폼은 스마트스토어 판매자, 커머스솔루션 구독자 등 다양한 사용자 분들께 서비스를 제공하는 범용 API 플랫폼입니다.
안정적 서비스 제공을 위해 모든 API 사용자에게 시간당 최대 API 호출 횟수 제한을 빠짐없이 적용하여 특정 사용자가 시스템 자원을 과점할 수 없도록 설계돼 있다고 합니다.

 

 

스마트 스토어 커머스API는 '토큰 버킷 알고리즘Token Bucket Rate Limiting Algorithm'을 적용하여 API 호출량을 제한합니다.
각 계층별로 1초 동안 처리가 가능한 API 호출 횟수를 정하여 해당 횟수를 초과하는 API 요청은 처리 불가 응답을 반환합니다. 이때 특정 계층에 호출 횟수가 남아있더라도 상위 계층의 호출 횟수가 초과되었다면 처리 불가 응답을 반환합니다.

 

 

커머스API 플랫폼에서 호출 횟수 산정 계층은 아래의 우선 순위를 기준으로 합니다.

1. API 수용량
2. 애플리케이션별 호출 허용량 – Rate limit
3. SELLER 토큰별 호출 허용량 – Quota limit

출처 : 네이버 - https://github.com/commerce-api-naver/commerce-api/discussions/6

 

API대행사의 동적 호출 허용량 설정 시 호출량 산정은 ① 애플리케이션 별 산정(Rate limit), ② 스토어 계정 별 산정(Quota limit) 이중으로 적용됩니다.

• Rate limit: 기존 애플리케이션 1개별 허용하는 호출 총량
• Quota limit: 'SELLER 타입' 인증 토큰 1개별 허용하는 호출 총량

솔루션/API대행사마다 다른 호출 허용량을 제공받습니다.(즉, 같은 API이더라도 솔루션/API대행사별로 다른 호출 허용량(토큰 수)이 다를 수 있습니다.)

 

 

1️⃣API 수용량

API 수용량은 “특정 API가 전체 사용자 대상으로 1초에 처리할 수 있는 총량”입니다.
API 수용량은 각 API별 기능 특성과 기술 사양에 따라 각기 다른 수용량으로 설정합니다. API 수용량은 서비스 운용 상황에 따라 유동적일 수 있습니다.

API 수용량을 초과하는 호출 요청에 대해서는 HTTP 429 응답을 반환합니다. 이때 애플리케이션별 호출 허용량(Rate limit)이 남아있는지는 고려하지 않습니다.

 

 

플랫폼이 정말 위험한 순간에는 “너는 아직 쿼터 남았으니 처리해줄게” 같은 여유가 없습니다. 서버가 버티려면 전체 상한선을 먼저 지켜야 합니다.
즉, API 수용량은 “전체 생존”을 위한 최후의 안전장치입니다.

 

2️⃣애플리케이션별 호출 허용량 – Rate limit

'애플리케이션'은 커머스API 플랫폼에 API를 호출할 때 필요한 자격 증명 정보 세트(애플리케이션 ID/Secret)입니다.(다시 말해 특정 애플리케이션 하나하나를 뜻합니다.) 특정 API의 호출 허용량 초과 여부 판단은 대상 API에 대한 시간 구간(1초 범위) 내 호출 횟수를 기준으로 하며 이때 횟수 산정은 애플리케이션 단위로 측정합니다.
애플리케이션 단위에서 특정 API에 대한 1초당 호출 가능 횟수(호출 허용량)를 "Rate limit" 이라 부릅니다.

Rate limit을 초과하는 호출 요청에 대해서는 HTTP 429 응답을 반환합니다.

 

이런 제한점은 한 솔루션이 버그로 한 API를 폭주 호출해도, 그 앱만 제한에 걸리고 다른 앱에는 영향이 줄어듭니다.
또한, 앱 단위로 공정성도 확보됩니다.

 

3️⃣Burst Max

Burst Max는 다음 1초의 Rate limit을 앞당겨 빌려옵니다.
커머스API 플랫폼에서는 대상 시간 범위(1초) 내 남은 Rate limit을 초과하는 API 요청이 발생할 경우 자동으로 Burst Max 기능을 활성화하여 다음 1초 구간의 Rate limit을 앞당겨 호출 횟수를 산정합니다.

단, Burst Max는 연속하여 사용할 수 없습니다.

 

 

4️⃣SELLER 토큰별 호출 허용량 - Quota limit

Quota limit은 'SELLER 타입' 인증 토큰 1개별 허용하는 호출 총량입니다.(단위 시간당[1초] 판매자 리소스 요청 수 제한)

Quota limit은 대상 대행사 시스템을 이용하는 특정한 최종 사용자(판매자)가 할당된 Rate limit을 과점하여 다른 최종 사용자의 커머스API 호출을 어렵게 만드는 일을 완화합니다.

Quota limit은 Rate limit에 대한 일정 비율로 산정됩니다. 대상 SELLER 인증 토큰으로는 Quota limit을 초과하는 API 호출이 불가능합니다. Quota limit에 적용을 받는 SELLER 인증 토큰들의 호출 허용량 총합은 Rate limit을 초과할 수 없습니다.

 

 

🪧API별 호출 허용량 확인

각 API별 호출 허용량은 API 호출에 대한 HTTP 응답 헤더(Response header)로 제공합니다.

 

• GNCP-GW-RateLimit-Replenish-Rate: 기본 초당 호출 허용량 수
• GNCP-GW-RateLimit-Burst-Capacity: 버스트 맥스(Burst Max)로 처리 가능한 초당 호출 허용량 수
• GNCP-GW-RateLimit-Remaining: 남은 호출 허용량 수
  
  
• GNCP-GW-Quota-Period: 호출 허용량의 단위 시간(대행사 애플리케이션: SECONDS 값으로 고정)
• GNCP-GW-Quota-Limit: 대상 SELLER 인증 토큰의 호출 허용량 수
• GNCP-GW-Quota-Remaining: 대상 SELLER 인증 토큰의 남은 호출 허용량 수

 

예시 응답

호출 허용량을 초과하는 API 호출 상황 (애플리케이션/SELLER 인증 토큰)

...애플리케이션별 호출 허용량이 다 된 경우 Remaining:"0"
GNCP-GW-RateLimit-Burst-Capacity:"4"
GNCP-GW-RateLimit-Replenish-Rate:"2"
GNCP-GW-RateLimit-Remaining:"0"

...SELLER 토큰별 호출 허용량이 다 된 경우 Remaining:"0"
GNCP-GW-Quota-Period:"SECONDS"
GNCP-GW-Quota-Limit:"4"
GNCP-GW-Quota-Remaining:"0"
...

 

 

 

📍예시 케이스

리소스 서버에서 제공하는 Open API 중 "/abc/xyz/{id}" 라는 API 가 있고, 이 API 그룹의 권한을 갖고 있는 대행사 애플리케이션 "A"가 있습니다.

그리고 이 A 애플리케이션을 사용하는 판매자는 "이순신과" "안중근" 2명이 있습니다.

각각 API 수용량은 10 / 애플리케이션별 호출 허용량 – Rate limit은 4 / SELLER 토큰별 호출 허용량 – Quota limit 은 2라고 가정하겠습니다.

 

 

1️⃣ SELLER 토큰 별 호출 허용량을 초과하는 경우

1초당 SELLER 토큰 별 호출 허용량은 2입니다. 1초 내에 안중근 셀러가 서드 파티인 A 애플리케이션을 통해 /abc/xyz/{id} 요청을 3 번 보냈다고 가정하겠습니다. (Burst Max은 무시)

 

1. 첫번째 요청 성공 / RateLimit-Remaining : 3 / Quota-Remaining : 1
2. 두번째 요청 성공/ RateLimit-Remaining : 2 / Quota-Remaining :0
3. 세번째 요청 실패 / 429 응답

 

이는 애플리케이션 호출 허용량이 남았다 하더라도 SELLER 토큰 별 호출 허용량을 초과하였기 때문에 요청에 실패하게 됩니다.

 

 

2️⃣ 애플리케이션 별 호출 허용량을 초과하는 경우

17시 03초에 A 애플리케이션 사용자 안중근과 이순신이 맥스 허용량인 2회씩 요청을 보냈다고 가정하겠습니다. 이때 네트워크 지연이나 재시도 처리 등의 이유로 17시 02.987 초에 보낸 안중근 요청이 서버에는 03초에 도착할 수 있습니다.

A 애플리케이션의 호출 허용량은 4인데 03초에 총 5회의 요청을 받았기 때문에, 이 중 가장 마지막 요청은 실패 처리됩니다.

플랫폼은 “순간 유입량” 기준으로 Rate를 계산하기 때문입니다.

 

이는 API 총 호출 허용량이 10으로 총 호출 허용량은 남았더라도 애플리케이션 별 호출 허용량을 초과 하였기 때문에 요청에 실패하게 됩니다.

 

 

3️⃣ API별 호출 허용량을 초과하는 경우

"/abc/xyz/{id}" API 의 총 호출 허용량은 10입니다. 이때 서비스 혼잡 상황이고 A 애플리케이션의 사용자(판매자)인 안중근, 이순신이 각각 요청을 한번만 보낸 다고 가정하겠습니다. 

하지만 A 애플리케이션말고, B,C,D 애플리케이션에서 각각 이번 초 구간에 3의 요청을 보낸 다고 하겠습니다.

요청 유입 시간 순서는 B → C → D 애플리케이션 사용자 → A 애플리케이션 안중근 → A 애플리케이션 이순신

 

B,C,D 애플리케이션의 요청을 모두 허용했으므로 API 의 허용량은 1입니다. A 애플리케이션의 안중근 요청은 허용 가능하므로 성공합니다. 그 다음 A  애플리케이션 이순신은 API별 호출 허용량을 초과하여 429 응답을 받게 됩니다.

 

 

 

 

🤔토큰 버킷 알고리즘을 활용하여 직접 구현해 본다면?

스마트 스토어에서 활용하는 기능을 제가 구현해본다면 어떻게 구현해볼지 상상해 봤습니다. API 요청을 처리하는 리소스 서버가 단일 인스턴스인지, 클러스터(분산 환경) 인지에 따라 호출 허용량(Rate/Quota)을 구현하는 방식은 자연스럽게 달라집니다.

하지만 주된 핵심은 하나인데요. 바로 “요청이 들어올 때마다 허용량을 차감하는 로직은 반드시 원자적(atomic) 이어야 한다.” 입니다.

 

 

단일 서버에서는 JVM/런타임 메모리 안에서 그 원자성을 확보하면 되고, 분산 환경에서는 여러 노드가 동일 상태를 공유해야 하므로 Redis 같은 중앙 상태 저장소와 서버 측 원자 실행(Lua)으로 구성할 수 있습니다.

 

 

1️⃣ 단일 서버 환경

단일 서버 환경에서는 “호출 허용량 상태”가 한 프로세스 메모리 안에만 존재하면 됩니다. 즉, 전역적으로 공유되는 상태는 싱글톤 객체로 두고, 토큰/카운터 조작을 AtomicLong, AtomicInteger, 혹은 CAS 알고리즘 기반으로 직접 구현하면 동시성 문제를 해결할 수 있습니다.

 

 

단일 서버이긴 하지만 요청은 동시로 들어옵니다. synchronized 같은 락도 가능하지만, QPS가 높아질수록 경합이 커집니다. 토큰의 수를 변화시키는 건 가벼운 작업이므로 토큰 버킷 상태를 하나의 구조로 보고, 락을 거는 것이 아닌 CAS 알고리즘을 사용하면 매우 가볍게 구현할 수 있습니다.

 

 

하지만 이런 방법은 서버가 2대로 늘어나는 순간, 각 서버가 독립된 토큰을 갖게 되어 “전체 허용량”을 컨트롤 할 수 없게 됩니다. 또한 서버 재시작 시 상태가 초기화된다는 단점도 있습니다.
이런 방식은 리소스 서버가 단일 인스턴스라는 전제가 유지될 때만 완전한 답입니다.

 

 

2️⃣ 분산 환경

러프하게 표현한 이미지

 

분산 환경에서는 Redis + Lua로 “전역 원자성”을 만들어 구현할 수 있을 거라 생각됩니다.

리소스 서버가 여러 대로 확장되는 순간, 가장 먼저 깨지는 것이 “허용량 상태의 일관성”입니다. 서버 A와 서버 B가 동시에 토큰을 차감할 때, 둘이 같은 상태값을 바라보지 않으면 이런 요청량 제한이 무의미해집니다. 그래서 분산 환경에서는 “전역 상태”를 한 곳에 모아야 하고, 그 상태 갱신은 경쟁 조건 없이 원자적으로 이뤄져야 합니다.

 

여기서 Redis가 강력한 이유는 두 가지입니다.

1. 중앙 상태 저장소로서의 역할: 모든 노드가 같은 버킷 상태를 본다.
2. 서버 측 원자 실행: Lua 스크립트를 Redis 내부에서 실행하면, 스크립트가 끝날 때까지 다른 명령이 끼어들지 않아 “토큰 값 확인 + 차감”을 하나의 트랜잭션처럼 처리할 수 있다.

 

처음에는 “분산락을 잡고 토큰을 차감”을 떠올리기 쉽습니다. 하지만 매 요청마다 락을 잡는 구조는 락 경합과 네트워크 왕복으로 인해 처리량이 떨어지기 쉽습니다. 반면 Redis Lua는

• 버킷 조회
• refill 계산
• 차감
• 저장
• 결과 반환

을 한 번의 호출로 처리할 수 있어, 락 없이도 동시성 문제가 사라집니다.

 

 

또한, 분산 환경에서 초 경계마다 카운터를 초기화하는 방식은 더 비효율적이라 생각합니다. 여러 서버/스케줄러가 개입되면서 약간의 지연이 생기고, 경계 시점에 오류가 있을 수 있습니다. 그래서 Redis에서도 단일 서버와 동일하게 마지막 refill 시각을 저장하고 계산으로 채우는 방법이 나을 것 같습니다.

 

 

키 설계는 계층 구조를 반영하면 됩니다.

• 애플리케이션 Rate limit: rl:{app_id}:{api}
• SELLER Quota limit: ql:{seller_token}:{api}

 

스마트스토어처럼 Rate와 Quota가 동시에 존재하면, “둘 다 통과해야 허용”이 기본 규칙입니다.
하나의 Lua 스크립트에서 Rate/Quota 버킷을 동시에 refill + 체크하고, 둘 다 성공일 때만 둘 다 차감해야 합니다.
이렇게 하면 분산 환경에서도 일관성이 유지됩니다.

 

 

결국 단일 서버와 분산 환경의 차이는 원자성을 보장하는 최선의 방법에 따라 달라지게 됩니다.

• 단일 서버: 새로운 외부 컴포넌트(캐시/DB/Redis 등)을 사용하지 않고 프로세스 메모리 안에서 Atomic/CAS로 해결
• 분산 환경: 공유 저장소(Redis)로 상태를 모으고, Lua 스크립트로 서버 측 원자 실행

 

📜참고

https://github.com/commerce-api-naver/commerce-api/discussions/6

사용량 제한 또는 호출량 제한이 있나요? · commerce-api-naver commerce-api · Discussion #6

https://github.com/commerce-api-naver/api-agency/discussions/12

[중요] '동적 호출 허용량' 전면 적용 안내 · commerce-api-naver api-agency · Discussion #12

https://apicenter.commerce.naver.com/docs/restriction

제약 사항 | 커머스API

https://github.com/commerce-api-naver/api-agency/discussions/23

동적 호출 허용량 전면 적용에 따른 대행사 대응 사항 · commerce-api-naver api-agency · Discussion #23