API 호출 제한·토큰 버킷 계산기 쉽게 이해하기 — 개념과 원리

대부분의 API는 클라이언트의 호출 속도를 제한하며, 그 방식으로 가장 널리 쓰이는 것이 토큰 버킷입니다. 짧은 순간 몰아서 보내는 것(버스트)은 허용하고, 그 뒤에는 일정한 속도로만 보내게 합니다. 이 계산기는 주어진 충전 속도와 버킷 크기에서 요청 묶음을 보내는 데 걸리는 최소 시간과, 일정 속도로 하루에 보낼 수 있는 요청 수를 구합니다. 대량 작업, 데이터 이전, 클라이언트 측 속도 조절을 계획할 때 유용합니다.

버킷만큼 100건은 한 번에 나가고, 그 뒤로는 초당 10개 충전 속도가 속도를 정합니다.

계산 방법

최소 시간(초) = max(0, (보낼 요청 수 − 버킷 크기) ÷ 충전 속도)
하루 요청 수 = 충전 속도 × 86,400(하루의 초)

버킷은 가득 찬 상태에서 시작한다고 가정합니다. 충전 속도는 초당 요청 수, 버킷 크기는 최대 버스트입니다.

원리

최대 B개의 토큰을 담는 버킷에 초당 r개씩 토큰이 채워진다고 생각해 보십시오. 요청 하나가 토큰 하나를 쓰며, 버킷이 비면 요청은 기다리거나 거부됩니다. 거부될 때는 보통 HTTP 429 Too Many Requests가 돌아옵니다. 가득 찬 상태라면 B개를 곧바로 보낼 수 있고, 그 뒤의 요청은 새 토큰이 필요한데 토큰은 초당 r개씩 들어오므로 남은 N − B개에 (N − B) ÷ r초가 걸립니다. 긴 시간으로 보면 버스트의 몫은 무시할 만해지고 처리량은 r에 가까워집니다. 비슷한 방식인 리키 버킷은 버스트를 허용하지 않고 출력을 일정한 속도로 고르게 만듭니다.

예제 풀이

입력값은 충전 속도 초당 10건, 버킷 100, 보낼 요청 1000건입니다.
처음 100건은 버스트로 한꺼번에 나갑니다.
남은 1000 − 100 = 900건은 초당 10건씩 보냅니다.
최소 시간은 900 ÷ 10 = 90초입니다.
일정 속도로 하루에 보낼 수 있는 양은 10 × 86,400 = 864,000건입니다.

다른 값은 그대로 두고 “충전 속도 (요청/s)”만 바꿔 계산기를 다시 돌린 결과입니다. 금색 점이 예제 값이며, 위에 값을 입력하면 내 값으로 다시 그려집니다.

충전 속도 (요청/s)	최소 시간 (s)
2.5	360
5	180
7.5	120
10	90
12.5	72
15	60
20	45

결과 해석

최소 시간은 하한값입니다. 네트워크 지연과 서버 응답 시간이 더해지고, 오류를 피하려면 보통 한도보다 조금 느리게 보내게 됩니다. 더 빨리 끝내야 한다면 할당량을 늘리거나, 일괄 처리 엔드포인트·캐시·조건부 요청으로 요청 수 자체를 줄이는 방법이 있습니다.

흔한 실수

버스트가 곧바로 다시 채워진다고 생각하는 경우입니다. 버스트 뒤에는 충전 속도로만 보낼 수 있습니다.
분당·일당 한도나 동시 요청 한도 같은 다른 제한을 놓치는 경우입니다.
429를 받고 바로 재시도하는 경우입니다. 토큰만 낭비하고 차단이 길어질 수 있습니다.

주의: 제공자마다 고정 창, 이동 창, 토큰 버킷 등 구현이 다르므로, 이 모델만 믿지 말고 공식 문서와 응답 헤더를 확인하십시오.

자주 묻는 질문

429 응답을 받으면 어떻게 해야 하나요?

Retry-After 헤더가 있으면 그 시간만큼 기다리고, 없으면 무작위 지연을 섞은 지수 백오프로 간격을 늘려 다시 시도합니다.

토큰 버킷과 고정 창 방식은 같은가요?

다릅니다. 고정 창은 구간마다 횟수를 초기화하므로 경계에서 두 번 몰아 보내기가 가능하고, 토큰 버킷은 연속해서 채워집니다.

출처: IETF RFC 6585, Additional HTTP Status Codes (429 Too Many Requests) · IETF RFC 9110, HTTP Semantics (Retry-After)

2026년 11월 8일 확인. 표준 공식과 RFC/IEEE 정의를 사용해 브라우저 안에서만 계산합니다. 입력한 내용은 어디에도 전송되지 않습니다.

입력값