API Rate Limit 계산기

API가 “분당 100요청” 같은 레이트 리밋(rate limit)을 걸어 두면, 내 요청을 어느 속도로 보내야 429(Too Many Requests)를 피할 수 있을까요? 이 계산기는 한도(요청 수)와 윈도우(초)를 입력하면 초당 허용 속도, 요청 사이의 최소 안전 간격(ms), 그리고 N개를 안전하게 다 보내는 데 걸리는 시간을 한 번에 계산해 줍니다.

배치 작업·크롤러·웹훅 재시도·대량 발송 스크립트를 설계할 때 “쉬는 시간(throttle)”을 얼마로 둘지 정확히 정할 수 있습니다. 동시 워커(concurrency)를 늘릴 때 워커당 간격이 어떻게 바뀌는지도 보여 줍니다. 응답 지연을 백분위로 분석하려면 응답시간 백분위 계산기를, 실제 요청을 만들어 테스트하려면 cURL 명령 생성기를 함께 사용하세요.

핵심 공식

레이트 리밋은 “윈도우(초)당 한도(요청 수)”로 정의됩니다. 여기서 모든 값이 파생됩니다.

• 허용 속도 = 한도 ÷ 윈도우 (req/s)
• 최소 안전 간격 = 윈도우 ÷ 한도 (초) = 1000 × 윈도우 ÷ 한도 (ms)
• 워커당 간격 = 동시 워커 수 × (윈도우 ÷ 한도) — 워커가 많을수록 각자는 더 천천히 보내야 전체 속도가 유지됩니다.
• N개 전송 시간 = N ÷ (한도 ÷ 윈도우) = N × 윈도우 ÷ 한도 (초)

예시: 분당 100요청

한도 100, 윈도우 60초라면 허용 속도는 약 1.67 req/s, 최소 간격은 600ms입니다. 요청마다 600ms 이상 띄우면 안전합니다.

• 500개를 보내려면 500 × 60 ÷ 100 = 300초(=05:00)가 걸립니다.
• 한 윈도우(60초)에 한도 100을 넘기면 429가 발생합니다. 500개라면 최소 ceil(500/100)=5개 윈도우가 필요합니다.
• 동시 워커 4개면 워커당 간격은 4 × 600ms = 2400ms로 두어야 합계 속도가 한도를 넘지 않습니다.

버스트와 토큰 버킷

많은 API는 평균 속도 외에 “버스트(burst)” 여유를 둡니다. 이 도구는 보수적으로 균등(steady) 속도를 가정하므로, 버스트를 허용하는 토큰 버킷 방식 API에서는 더 공격적으로 보낼 수 있습니다. 그래도 안전 간격을 지키면 429를 거의 확실히 피할 수 있습니다.

실제 API들의 공개 레이트 리밋

이 값들을 그대로 한도·윈도우 칸에 넣어 보면 각 API에 맞는 안전 간격이 바로 나옵니다(공식 문서 기준의 대표값이며 요금제·엔드포인트별로 다를 수 있음).

429 응답 헤더 읽는 법

계산기로 간격을 정해도, 429가 떴을 때는 추측하지 말고 응답 헤더를 따라야 합니다. 자주 쓰이는 헤더는 다음과 같습니다.

흔한 실수 / 함정

• 이 계산기의 안전 간격은 윈도우 안에서 한도를 몰아 쓰지 않는 균등(steady) 속도를 가정합니다. 윈도우 초반에 한도를 다 써 버린 뒤 “경계 지나면 리셋되겠지” 하고 다음 윈도우 시작과 함께 또 몰아 보내면, 두 윈도우 경계에 걸쳐 순간 속도가 2배가 되어 슬라이딩 윈도우 리미터에서 429를 맞습니다. 평균이 아니라 매 순간의 속도를 한도 아래로 유지하세요.
• Retry-After가 응답에 들어 있으면 계산기 값이 아니라 그 헤더를 따르세요. 계산기 간격은 정상 운영용 페이싱이고, 헤더는 서버가 지금 강제하는 실제 대기 시간입니다.