Telm은 API를 두 가지 방식으로 계측합니다: 분당 속도 제한(버스트 상한)과 일일 할당량(UTC 하루 동안의 총예산)입니다. 둘 다 요금제에 따라 확장됩니다. 계측되는 모든 응답은 X-Quota-Limit, X-Quota-Used, X-Quota-Reset을 반환하므로 남은 예산을 항상 알 수 있으며, 두 제한 모두 초과 시 Retry-After 헤더와 함께 429를 반환합니다.
1두 가지 제한: 분당 속도와 일일 할당량
두 개의 별개 상한이 있습니다. 분당 속도 제한은 임의의 1분 안에 할 수 있는 요청 수를 제한해 버스트를 완만하게 만듭니다. 일일 할당량은 전체 예산으로, UTC 하루 전체에 걸쳐 할 수 있는 계측 호출 수를 제한합니다.
둘은 독립적입니다. 일일 할당량이 넉넉히 남았는데도 분당 제한에 걸릴 수 있고(단지 너무 빠르게 보내는 것), 분당 제한에는 한참 못 미쳤는데도 일일 할당량을 소진할 수 있습니다(하루치를 다 쓴 것). 둘 다 429 상태를 반환하지만 이유가 다릅니다. 본문의 오류 코드를 확인해 구분하세요.
- 분당 속도 제한 — 버스트 상한, 매분 초기화.
- 일일 할당량 — 하루의 총 계측 호출, UTC 자정에 초기화.
- 할당량은 계정당 한 번 집계되어 모든 키가 공유합니다.
2요금제별 일일 할당량
일일 할당량은 UTC 하루당 할 수 있는 계측 API 호출 수이며, 요금제에 따라 다릅니다. 카운터는 모든 키에 걸쳐 공유되고, 여러분이 관리하는 그룹 중 가장 좋은 요금제를 따릅니다. 유료 구독이 없으면 Free 등급입니다.
기간은 UTC 달력의 하루이므로, 사용 카운터는 UTC 자정에 0으로 초기화됩니다. 배치 스팸 검사는 요청 전체가 아니라 배치의 항목당 한 호출씩 비용이 듭니다.
- Free — 하루 100회 호출.
- Basic — 하루 1,000회 호출.
- Pro — 하루 10,000회 호출.
- Business — 하루 50,000회 호출.
3요금제별 분당 속도 제한
일일 할당량에 더해, 각 API 키는 요금제 등급에 따라 분당 요청 수가 제한됩니다. 이것은 완만화 제한입니다. 일일 예산이 아직 많이 남아 있어도, 단일 클라이언트가 1초에 거대한 스파이크를 보내는 것을 막습니다.
별도로, 플랫폼 안정성을 위해 넓은 범위의 IP당·계정당 상한이 전체 API에 적용됩니다. 정상 사용 — 꾸준하고 조절된 요청 — 에서는 이것들에 결코 닿지 않습니다. 오직 남용적인 버스트에서만 발동합니다.
- Free와 Basic — 분당 60회 요청.
- Pro — 분당 600회 요청.
- Business — 분당 1,800회 요청.
- 요청을 한꺼번에 쏘지 말고 고르게 분산하세요.
4남은 예산 읽기
얼마나 남았는지 추측할 필요가 전혀 없습니다. 계측되는 모든 응답은 — 성공이든 실패든 — 세 개의 헤더를 포함합니다. X-Quota-Limit(일일 한도), X-Quota-Used(오늘 지금까지 쓴 호출 수), X-Quota-Reset(카운터가 초기화되는 UTC 시각)입니다.
스팸 검사 엔드포인트는 응답 본문의 quota 객체 안에 같은 숫자를 그대로 담으므로, 헤더를 파싱하지 않고도 남은 예산을 읽을 수 있습니다. 이를 사용해 여러분 자신의 요청 속도를 조절하고, 소진되기 전에 스스로 경고하세요.
- X-Quota-Limit — 일일 호출 한도.
- X-Quota-Used — 오늘 지금까지 쓴 호출 수.
- X-Quota-Reset — UTC 초기화 시각(RFC 3339).
- 스팸 검사 응답에도 같은 필드를 가진 quota 객체가 포함됩니다.
5429에서 무슨 일이 일어나는가
어느 한 제한을 넘으면 API는 몇 초를 기다려야 하는지 알려주는 Retry-After 헤더와 함께 HTTP 429를 반환합니다. 분당 속도 제한의 경우 Retry-After는 약 1분입니다. 일일 할당량의 경우 본문에 daily_quota_exceeded 코드와 함께 요금제, 한도, 사용 수, 초기화 시각, 업그레이드 안내가 담기며, Retry-After는 UTC 자정까지 카운트다운됩니다.
429를 처리하는 올바른 방법은 물러나 Retry-After 지연 후에 재시도하는 것이지, 엔드포인트를 두드려대는 것이 아닙니다. 잘 동작하는 클라이언트는 헤더를 읽고 멈춥니다. 즉시 계속 재시도하는 클라이언트는 그저 계속 차단된 채로 남습니다.
- 429 rate_limit_exceeded — 너무 빠르게 보냈습니다. 약 1분 기다리세요.
- 429 daily_quota_exceeded — 하루치를 다 썼습니다. UTC 초기화까지 기다리거나 업그레이드하세요.
- 재시도 전에 항상 Retry-After 헤더를 존중하세요.