API 쿼터 가이드
카페24 API는 안정적인 서비스 운영을 위해 호출량을 제한합니다.
제한은 총량 제어와 유량 제어 두 계층으로 함께 동작하며, 어느 하나라도 초과하면 429 Too Many Requests 응답이 반환됩니다.
📚 목차
🧭 쿼터 2계층 구조
두 제한은 서로 다른 것을 막습니다. 총량은 일정 시간 동안 쓸 수 있는 전체 양을, 유량은 순간적인 몰림을 제어합니다.
① 총량 제어 (쿼터) ② 유량 제어 (Leaky Bucket)
┌──────────────────────────┐ ┌──────────────────────────┐
│ 10분 단위로 집계 │ │ 버킷 용량 40 │
│ · 호출수 3,000회 │ │ 초당 2회씩 감소 │
│ · 호출시간 600초 │ │ │
│ │ │ 순간 폭주를 차단 │
│ 장시간 누적 사용량 제어 │ │ │
└──────────────────────────┘ └──────────────────────────┘
│ │
└──────────────┬───────────────────────┘
▼
초과 시 429 Too Many Requests
| 구분 | ① 총량 제어 | ② 유량 제어 |
|---|---|---|
| 집계 단위 | 10분 | 실시간(초 단위) |
| 제한 대상 | 호출 수, 호출 시간 | 동시/연속 호출 속도 |
| 막는 상황 | 하루 종일 조금씩 과하게 쓰는 경우 | 짧은 시간에 몰아서 호출하는 경우 |
| 확인 방법 | 초과 시 429 응답 | X-Api-Call-Limit 응답 헤더 |
두 제한은 독립적입니다. 초당 호출 속도를 충분히 낮춰도 10분 총량을 넘기면 429가 발생하고, 반대로 총량에 여유가 있어도 순간적으로 몰아서 호출하면 429가 발생합니다.
📊 기본 쿼터
별도로 설정하지 않는 한 다음 값이 기본 적용됩니다.
| 항목 | 기본값 | 설명 |
|---|---|---|
| 호출 수 | 10분당 3,000회 | 10분 동안 허용되는 총 API 요청 건수 |
| 호출 시간 | 10분당 600초 | 10분 동안 API 처리에 사용할 수 있는 누적 시간 |
호출 시간이란
응답이 느린 API를 반복 호출하면 호출 수에 여유가 있어도 호출 시간이 먼저 소진될 수 있습니다.
예) 평균 응답 1초인 API를 10분간 600회 호출
호출 수 : 600 / 3,000 → 여유 있음
호출 시간: 600 / 600초 → 소진 ⚠️ 이후 요청은 429
대량 조회 시에는 응답이 무거운 API를 반복 호출하기보다 limit 파라미터로 페이지 크기를 키워 호출 횟수 자체를 줄이는 편이 쿼터 소모에 유리합니다.
자세한 조회 파라미터 사용법은 GET API 사용 가이드를 참고하세요.
쇼핑몰별로 별도 쿼터가 설정된 경우 위 기본값 대신 해당 설정이 적용됩니다.
🪣 순간 유량 제한
총량과 별개로, 순간적인 호출 폭주는 Leaky Bucket(누수 버킷) 방식으로 제어됩니다.
동작 방식
요청 1건 = 물 1방울
│
▼
┌─────────┐
│ ▓▓▓▓▓▓▓ │ 버킷 용량: 40
│ ▓▓▓▓▓▓▓ │ → 가득 차면 429
└────┬────┘
│ 초당 2회씩 자동 감소
▼
| 항목 | 값 | 의미 |
|---|---|---|
| 버킷 용량 | 40 | 순간적으로 쌓일 수 있는 최대 요청 수 |
| 누수 속도 | 초당 2회 | 1초마다 버킷에서 2건씩 빠져나감 |
실무 기준
- 초당 2회 이하로 호출하면 버킷이 차지 않아 제약을 받지 않습니다.
- 일시적으로 초당 2회를 넘겨도 버킷 용량(40)만큼은 여유가 있어 짧은 폭주는 허용됩니다.
- 지속적으로 초당 2회를 초과하면 버킷이 가득 차 429가 발생합니다.
📮 X-Api-Call-Limit 헤더
모든 API 응답에는 현재 버킷 상태가 헤더로 포함됩니다.
X-Api-Call-Limit: 1/40
│ │
│ └─ 버킷 용량
└──── 현재 사용량
확인 예제
curl -i -X GET \
'https://yourmall.cafe24api.com/api/v2/admin/products' \
-H 'Authorization: Bearer {access_token}'
# 응답 헤더
# HTTP/1.1 200 OK
# X-Api-Call-Limit: 1/40
Node.js
const response = await axios.get(url, { headers });
const callLimit = response.headers['x-api-call-limit']; // "1/40"
const [used, capacity] = callLimit.split('/').map(Number);
// 버킷이 80% 이상 차면 호출 속도를 늦춘다
if (used / capacity > 0.8) {
await new Promise(resolve => setTimeout(resolve, 1000));
}
Python
response = requests.get(url, headers=headers)
call_limit = response.headers.get('X-Api-Call-Limit') # "1/40"
used, capacity = map(int, call_limit.split('/'))
# 버킷이 80% 이상 차면 호출 속도를 늦춘다
if used / capacity > 0.8:
time.sleep(1)
429가 발생한 뒤에 대응하는 것보다, 이 헤더를 지속적으로 확인하며 미리 속도를 조절하는 편이 안정적입니다.
🔀 API별 차이
| API | 총량 쿼터 | 유량 제한 | 비고 |
|---|---|---|---|
| Admin API | 10분 3,000회 / 600초 | 버킷 40, 초당 2회 감소 | Access Token 기준으로 집계 |
| Front API (Basic 인증) | 기본 쿼터 적용 | 버킷 40, 초당 2회 감소 | 인증된 요청으로 처리 |
| Front API (비인증) | 낮은 한도 적용 | 낮은 한도 적용 | 안정적 운영을 위해 Basic 인증 권장 |
| D.Collection API | — | IP당 1분에 최대 40회 | 별도 정책 적용 |
Front API는 인증 여부에 따라 호출 제한이 차등 적용됩니다.
client_id만 전달하는 비인증 방식은 제한이 낮게 적용되므로, 서비스 운영 시에는 Basic 인증 방식을 사용하세요.
인증 방법은 OAuth 2.0 인증 가이드를 참고하세요.
🐛 429 대응 방법
응답 형태
HTTP/1.1 429 Too Many Requests
X-Api-Call-Limit: 40/40
지수 백오프 재시도
429를 받으면 즉시 재시도하지 말고, 대기 시간을 점차 늘려가며 재시도합니다.
Node.js
async function requestWithRetry(config, maxRetries = 5) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await axios(config);
} catch (error) {
if (error.response?.status !== 429) {
throw error;
}
// 1초 → 2초 → 4초 → 8초 → 16초
const waitMs = Math.pow(2, attempt) * 1000;
console.warn(`429 발생, ${waitMs}ms 후 재시도 (${attempt + 1}/${maxRetries})`);
await new Promise(resolve => setTimeout(resolve, waitMs));
}
}
throw new Error('재시도 횟수를 초과했습니다');
}
Python
import time
def request_with_retry(method, url, headers, max_retries=5, **kwargs):
for attempt in range(max_retries):
response = requests.request(method, url, headers=headers, **kwargs)
if response.status_code != 429:
return response
# 1초 → 2초 → 4초 → 8초 → 16초
wait_sec = 2 ** attempt
print(f'429 발생, {wait_sec}초 후 재시도 ({attempt + 1}/{max_retries})')
time.sleep(wait_sec)
raise Exception('재시도 횟수를 초과했습니다')
대량 처리 시 권장 패턴
| 상황 | 권장 방법 |
|---|---|
| 전체 목록 수집 | limit을 최대로 지정해 호출 횟수를 줄이고, 페이지 간 간격을 둠 |
| 다건 등록/수정 | 병렬 호출 대신 순차 호출 + 요청 간 최소 0.5초 간격 |
| 배치 작업 | 업무 시간대를 피해 분산 실행 |
| 실시간 연동 | 변경분만 조회하도록 date 계열 파라미터로 범위 축소 |
재시도 로직 없이 실패한 요청을 즉시 반복하면 버킷이 계속 가득 찬 상태로 유지되어 정상 요청까지 차단됩니다. 반드시 대기 시간을 두고 재시도하세요.
📚 관련 문서
- API Status Code 가이드 — 429를 포함한 전체 상태 코드
- OAuth 2.0 인증 가이드 — Admin/Front API 인증 방법
- GET API 사용 가이드 — 조회 파라미터로 호출 횟수 줄이기