사용량 제한 또는 호출량 제한이 있나요?

[commerce-api-naver]

Q. 사용량 제한 또는 호출량 제한이 있나요?

A. API별 초당 호출 횟수를 산정하여 정해진 횟수 이상의 호출을 제한합니다.

커머스API Docs에서의 제한 내용을 아래와 같이 설명드립니다.

호출 허용량 (Rate limit)

커머스API 플랫폼은 모든 사용자 대상으로 시간당 최대 API 호출 횟수 제한을 적용합니다.
다양한 사용자분들께 안정적인 서비스를 지속적으로 제공하려는 목적으로 이 제한을 '호출 허용량' 또는 '요청량(수) 제한_{Rate limit}'으로 칭합니다.

기준

• 알고리즘: 토큰 버킷 알고리즘 (Token Bucket Rate Limiting Algorithm)
• 산정 단위: 호출 애플리케이션별 API 당 호출 횟수
• 구간 단위: 1초당
  • 호출 허용량의 단위는 'RPS'_{Requests per second}

초과 호출의 처리

호출 허용량을 초과하는 API 호출은 요청 처리를 진행하지 않으며 무조건 실패 응답을 반환합니다.
이때 요청에 대한 결과는 항상 HTTP 429 응답으로 반환합니다.

호출 허용량 계층

커머스API 플랫폼은 호출 애플리케이션에 따라 2–3가지 호출 허용량 계층을 두어 안정적 서비스 운용의 지속성을 도모합니다.
하위 계층의 호출 허용량이 남아있더라도 상위 계층의 호출 허용량이 남아있지 않다면 요청 처리를 제한합니다.

1. API 수용량
2. 애플리케이션 호출 허용량 – Rate limit
3. SELLER 토큰별 호출 허용량 – Quota limit
   _{(Quota limit은 커머스솔루션, API대행사 애플리케이션만 해당함)}

1. API 수용량

플랫폼 인스턴스 전체 사용자로부터 대상 API 서비스가 1초당 처리할 수 있는 총 요청량.

API별 특성과 기술 사양 등에 따라 결정되며 서비스 상황에 따라 설정 내용은 수시로 변경될 수 있습니다.
이 정보는 사용자에겐 제공하지 않습니다.

2. Rate limit – 애플리케이션 호출 허용량

사용자 애플리케이션이 특정 API를 1초당 호출할 수 있는 허용량.

애플리케이션의 호출 허용량 산정은 호출한 API별로 별도 산정합니다.

예시1: 호출 허용량 산정과 초기화

_{(Burst Max 규격은 고려하지 않음. API 수용량은 허용 범위 이내임을 가정. 각 API별 Rate limit은 2를 가정.)}

호출 회차	호출 시간	호출 API	API 호출 성공 여부	남은 호출 횟수
1회차	00:00:01.381	[상품] 카테고리 조회	성공	1
2회차	00:00:01.487	[상품] 카테고리 조회	성공	0
3회차	00:00:01.736	[상품] 카테고리 조회	실패 (429)	0
4회차	00:00:02.390	[상품] 카테고리 조회	성공	1

1. 3회차 호출은 시간 구간 내 호출 허용량(초당 2회)을 초과하는 API 호출로 처리 실패(HTTP 429) 응답
   • 이 시간 구간의 호출은 1회차, 2회차로 소진
2. 이후 새로운 시간 구간에 진입하여 호출 허용량 복원으로 4회차 호출은 성공 응답

예시2: API별 호출 허용량 산정

_{(Burst Max 규격은 고려하지 않음. API 수용량은 허용 범위 이내임을 가정. 각 API별 Rate limit은 2를 가정.)}

호출 회차	호출 시간	호출 API	API 호출 성공 여부	남은 호출 횟수
1회차	00:00:01.381	[상품] 카테고리 조회	성공	1
2회차	00:00:01.412	[상품] 발송 처리	성공	1
3회차	00:00:01.487	[상품] 카테고리 조회	성공	0
4회차	00:00:01.736	[상품] 카테고리 조회	실패 (429)	0
5회차	00:00:01.790	[상품] 발송 처리	성공	0

1. 4회차 호출과 5회차 호출은 서로 다른 API에 대한 호출로 각 호출 허용량과 횟수는 별도 산정

3. Quota limit – SELLER 토큰별 호출 허용량

Note

이 규격은 커머스솔루션, API대행사 애플리케이션에만 적용합니다.

커머스API센터에서 발급한 '내 스토어 애플리케이션'은 Quota limit이 적용되지 않습니다.

SELLER 토큰별 특정 API를 1초당 호출할 수 있는 허용량.

이 규격은 단일 애플리케이션을 다수의 최종 사용자_{End user}가 사용하는 형태의 애플리케이션에만 적용합니다. (커머스솔루션, API대행사)
특정한 사용자가 애플리케이션 Rate limit을 과점하여 다른 사용자가 API 호출에 따른 수혜를 누리지 못하는 것을 완화합니다.

예시3: Quota limit의 동작

_{(Burst Max 규격은 고려하지 않음. API 수용량은 허용 범위 이내임을 가정. 각 API별 Rate limit은 5, Quota limit은 2임을 가정. 동일 API 호출을 가정.)}

호출 회차	호출 시간	SELLER 토큰 리소스	API 호출 성공 여부	남은 Rate limit	남은 Quota limit
1회차	00:00:01.102	판매자A	성공	4	1
2회차	00:00:01.187	판매자A	성공	3	0
3회차	00:00:01.275	판매자A	실패 (429)	3	0
4회차	00:00:01.281	판매자B	성공	2	1
5회차	00:00:01.383	판매자C	성공	1	1
6회차	00:00:01.619	판매자C	성공	0	0
7회차	00:00:01.709	판매자B	실패 (429)	0	1
8회차	00:00:02.417	판매자A	성공	4	1
9회차	00:00:02.738	판매자B	성공	3	1

1. 3회차 호출은 '판매자A'의 SELLER 토큰에 대한 Quota limit을 초과하여 실패 처리
2. 7회차 호출은 애플리케이션에 대한 Rate limit을 초과하여 실패 처리

Burst Max 규격

다음 시간 구간(1초)의 Rate limit을 앞당겨 사용하는 기능입니다.

대상 시간 구간에 Rate limit을 초과하는 API 요청이 발생할 경우 Burst Max 사용이 가능한 조건이라면 자동으로 기능을 활성화합니다.
따라서 Burst Max 활성화 시 대상 시간 구간의 Rate limit은 항상 평상시의 2배가 됩니다.
단, Burst Max는 연속하여 사용할 수 없으며 Quota limit에는 적용하지 않습니다.

예시4: Burst Max 작동 예

_{(API 수용량은 허용 범위 이내임을 가정. 각 API별 Rate limit은 2를 가정. 동일 API 호출을 가정.)}

호출 회차	호출 시간	API 호출 성공 여부	남은 호출 횟수	부여된 호출 횟수	🔥 Burst Max
1회차	00:00:01.102	성공	1	2	사용 가능
2회차	00:00:01.386	성공	0	2	사용 가능
3회차	00:00:01.808	성공	1 (기본: 0 / 🔥: 1)	4	🔥 활성화
---	---	---	---	---	---
4회차	00:00:02.361	성공	0	1	사용 불가
5회차	00:00:02.733	실패 (429)	0	1	사용 불가
---	---	---	---	---	---
6회차	00:00:03.299	성공	1	2	사용 가능
7회차	00:00:03.321	성공	0	2	사용 가능
8회차	00:00:03.531	성공	1 (기본: 0 / 🔥: 1)	4	🔥 활성화
9회차	00:00:03.610	성공	0 (기본: 0 / 🔥: 0)	4	🔥 활성화
10회차	00:00:03.777	실패 (429)	0 (기본: 0 / 🔥: 0)	4	🔥 활성화
---	---	---	---	---	---
11회차	00:00:04.390	실패 (429)	0	0	사용 불가

1. 3회차 호출에서는 기본 Rate limit을 모두 사용하여 다음 시간 구간(00:00:02)의 기본 Rate limit을 앞당겨 사용하기에 호출 성공
2. 4회차 호출에서는 이전 시간 구간(00:00:01)에서 현재 시간 구간(00:00:02)의 기본 Rate limit을 앞당겨 1회 사용하였기에 현재 시간 구간의 '부여된 호출 횟수'는 1RPS (= 2RPS - 1RPS)
3. 5회차 호출에서는 이전 시간 구간(00:00:01)에서 Burst Max가 활성화되었기에 연속하여 사용할 수 없음으로 호출 실패
4. 10회차 호출에서는 기본 Rate limit과 Burst Max 활성화로 앞당긴 Rate limit을 모두 사용하였기에 초과하는 호출은 실패
5. 11회차 호출에서는 이전 시간 구간(00:00:03)에서 Rate limit을 앞당겨 모두 사용하였기에 현재 시간 구간(00:00:04)의 '부여된 호출 횟수'는 0RPS (= 2RPS - 2RPS)

추가 정보

HTTP 응답 헤더로 호출 허용량 구성 확인

상세한 내용은 커머스API Docs에서 확인하세요.

HTTP 응답 헤더 항목	설명
GNCP-GW-RateLimit-Replenish-Rate	설정된 Rate limit (총 호출 횟수)
GNCP-GW-RateLimit-Burst-Capacity	Burst Max 적용 시 가능한 Rate limit
GNCP-GW-RateLimit-Remaining	현재 남은 호출 횟수 (Burst Max 적용 시 기준)

'내 스토어 애플리케이션'의 Rate limit

커머스API센터에서 발급한 '내 스토어 애플리케이션'은 모든 API의 Rate limit을 기본 2RPS로 고정하여 서비스를 제공합니다.
이 내용은 사용자가 직접 변경할 수 없습니다.

Tip

💡 대규모 서비스 구성을 위한 제안

제공된 호출 허용량을 최대한 효율적으로 사용할 수 있도록 대규모 서비스에서의 API 호출은 Queue 구조에 적재하는 것을 권장합니다.
스케쥴러가 API별 시간당 Rate limit 범위 내에서 Queue 구조체에 적재된 API 호출 요청을 1초 간격의 HTTP 요청으로 발생시키면 원활한 커머스API 운용에 큰 도움이 됩니다.

---

(마지막 변경일: 2026년 6월 4일)

_{실제 서비스 사용에서는 네트워크 전송에 따른 지연, 데이터 처리에 따른 지연, 서버 컴퓨터의 시차, 서비스 캐시 등 다양한 환경 변수에 따라 호출량 제한 관련 처리에 수 밀리초에서 수 초의 오차가 있을 수 있습니다. 게시한 모든 예시에서는 이러한 오차를 감안하지 아니하며 기술 규격에 대한 사용자 이해를 돕기 위해서만 작성되었습니다. Quota limit은 일부 API 호출에 적용되지 않을 수 있습니다.}