요청률 제한 (Rate Limit)

요청률 제한(Rate Limit)은 일정 시간에 서비스로 보낼 수 있는 요청 수나 처리량의 상한을 정하는 제어 방식입니다. API에서는 호출 횟수뿐 아니라 입력·출력 토큰 양에도 각각 한도를 둘 수 있습니다. 같은 총량을 보내더라도 짧은 순간에 요청이 몰리는지, 어느 계정의 사용량으로 합산되는지에 따라 제한에 걸리는 시점이 달라집니다.

요청 수와 토큰 양의 계량 기준

짧은 질문을 여러 번 보내는 작업과 긴 문서를 한 번 보내는 작업은 서버에 주는 부담이 다릅니다. 요청 횟수만 세면 두 작업의 차이를 충분히 반영하기 어렵습니다. 언어 모델 API가 토큰 기준을 함께 두는 이유입니다. 요청 수에 여유가 남아 있어도 긴 문서를 연달아 입력하면 입력 토큰 한도를 먼저 채울 수 있으며, 긴 답변을 많이 생성하면 출력 쪽 한도가 병목이 됩니다.

앤트로픽의 요청률 제한 문서는 Messages API의 기준으로 분당 요청 수인 RPM, 분당 입력 토큰 수인 ITPM, 분당 출력 토큰 수인 OTPM을 구분합니다. 세 지표는 각각 다른 사용량을 셉니다. 한 번의 호출도 요청 수와 토큰 사용량에 함께 영향을 주므로, 어떤 기준을 넘었는지 확인해야 호출 간격과 문서 길이 중 무엇을 조정할지 판단할 수 있습니다.

분당 한도라는 표기가 매분 정각에 사용량을 모두 지운다는 뜻은 아닙니다. 같은 문서는 짧은 시간 구간에서도 제한이 적용될 수 있으며, 허용량이 시간에 따라 보충되는 토큰 버킷 방식을 사용한다고 설명합니다. 한동안 쉬었다가 요청을 한꺼번에 보내는 방식과 일정한 간격으로 보내는 방식은 평균 요청 수가 같아도 결과가 달라질 수 있습니다. 한도는 보장된 처리 속도와도 구별합니다.

동시 실행 수와 지출 한도의 차이

동시 실행 수는 한 시점에 진행 중인 작업의 수입니다. 요청률은 일정 시간 동안 들어오는 양을 셉니다. 요청 하나가 오래 걸리면 적은 호출 횟수로도 진행 중인 작업이 쌓이고, 요청이 빨리 끝나면 동시 실행 수가 낮아도 짧은 시간에 많은 호출이 지나갑니다. 작업자 수만 줄이는 것으로 요청률을 정확히 제어하기 어려운 이유입니다. 전송 간격과 진행 중인 작업 수를 별도 설정으로 다루면 두 제한을 구분하기 쉽습니다.

지출 한도는 API 사용 비용의 상한이며 요청률 제한과는 해제 조건이 다릅니다. 2026년 10월 11일 확인한 앤트로픽 문서는 공급자가 이용 등급별로 강제하는 월 지출 상한에 도달하면 HTTP 429를 반환하고 retry-after 헤더는 보내지 않는다고 설명합니다. 사용자가 직접 정한 지출 한도는 일반적으로 HTTP 400을 반환하며, Claude Code 워크스페이스에는 별도 예외가 있습니다. 429라는 숫자만 보고 잠시 뒤 같은 요청을 반복하는 대응은 충분하지 않습니다.

한도를 합산하는 범위도 서비스마다 다릅니다. HTTP 429를 정의한 RFC 6585는 사용자를 식별하는 방법이나 요청을 세는 범위를 하나로 고정하지 않습니다. 특정 자원, 서버 전체, 여러 서버의 요청을 합산하는 구현이 가능합니다. 프로그램을 여러 개 실행하더라도 같은 계정이나 조직의 한도를 공유한다면 사용량은 함께 누적됩니다. 호출 프로그램 하나의 기록만으로는 실제 합산량을 놓칠 수 있습니다.

응답에 따른 대기와 재시도

HTTP 429는 정해진 시간에 요청이 너무 많이 들어왔음을 알리는 상태 코드입니다. RFC 6585는 서버가 재시도 전 대기 시간을 안내하는 Retry-After 헤더를 포함할 수 있다고 규정합니다. 헤더가 항상 온다는 보장은 없으며, 반환된 경우에는 서비스가 안내한 대기 조건을 확인합니다. 헤더가 없다면 오류 본문과 해당 API 문서에서 제한의 종류와 해제 조건을 먼저 구분하는 방식이 적절합니다.

일시적인 요청률 초과라면 대기열에서 전송을 늦추고, 실패가 이어질 때 재시도 간격을 늘리는 백오프를 적용할 수 있습니다. 이는 허용량이 회복될 시간을 주는 운영 방식입니다. 기다리는 동안 새 작업과 재시도 작업을 계속 무제한으로 추가하면 다시 요청이 몰립니다. 재시도 횟수와 전체 대기 시간을 정하고, SDK가 이미 자동 재시도하는지도 함께 확인하면 응용 프로그램의 반복 호출과 겹치는 상황을 줄일 수 있습니다.

원인을 추적할 때는 오류가 난 시각, 어떤 한도를 넘었는지, 응답 헤더의 남은 허용량을 함께 기록합니다. 앤트로픽 문서는 요청 수와 입력·출력 토큰의 한도 및 남은 양을 알려 주는 응답 헤더를 설명합니다. 요청 수가 원인이라면 전송 간격을, 토큰 양이 원인이라면 입력이나 출력의 크기를 우선 살펴볼 수 있습니다. 지출 상한에 걸린 요청은 간격을 늘리는 조치만으로 복구되지 않으므로 별도로 처리합니다.