클로드 API 속도 제한 정리, 사용 등급과 분당 한도·429 대응·응답 헤더 읽는 법 (2026년 10월 기준)

최종 수정일: 2026년 10월 26일

클로드 API의 한도는 두 종류입니다. 한 달 동안 쓸 수 있는 금액의 상한인 지출 한도, 그리고 일정 시간 안에 보낼 수 있는 요청과 토큰의 상한인 속도 제한입니다. 둘 다 조직 단위로 적용되고, 사용 등급에 따라 수치가 달라집니다. 아래는 2026년 10월 26일 공식 속도 제한 문서를 기준으로 등급별 지출 한도, 분당 요청·토큰 한도, 캐시가 한도에 미치는 영향, 응답 헤더, 429가 났을 때의 대응을 정리했습니다.

이 글은 공식 문서를 읽고 정리한 글이고, 직접 API를 호출해 한도를 측정한 결과는 아닙니다. 오류 코드 전반은 API 오류 코드 글에서 다룹니다.

한도는 두 종류입니다

• 지출 한도: 조직이 한 달에 API에 쓸 수 있는 최대 비용입니다.
• 속도 제한: 일정 기간 동안 조직이 보낼 수 있는 API 요청의 최대 수입니다. 메시지 API에서는 분당 요청 수, 분당 입력 토큰 수, 분당 출력 토큰 수로 잽니다.

공식 문서에 따르면 서비스가 정한 한도는 조직 단위로 적용되고, 조직의 워크스페이스에는 사용자가 따로 더 낮은 한도를 정할 수 있습니다. 한도는 사용 기록과 계정 상태에 따라 자동으로 배정되는 사용 등급으로 정해지고, 사용하면서 더 높은 등급으로 올라갈 수 있습니다. 새 조직이나 사용 기록이 적은 조직은 표준 한도보다 낮은 평가 등급에서 시작할 수 있고, 기록이 쌓이면 자동으로 올라간다고 문서가 설명합니다.

등급별 월 지출 한도

시작, 빌드, 스케일 등급에는 달력 기준 한 달 동안 쓸 수 있는 지출 상한이 있습니다.

사용 등급	월 지출 한도
Start	500달러
Build	1,000달러
Scale	200,000달러

커스텀 등급은 월 지출 한도가 없고 담당 팀과 정합니다. 자신의 조직이 어느 등급인지와 현재 한도는 콘솔의 속도 제한 페이지에서 볼 수 있다고 문서가 안내합니다. 콘솔 화면의 한국어 메뉴 이름은 이 글에서 확인하지 못했습니다.

지출 한도에 닿으면 생기는 일

등급의 지출 한도에 닿으면 다음 달 1일 00:00(UTC)까지 API 사용이 멈추고, 요청은 HTTP 429를 받습니다. 문서의 예시 응답은 다음과 같습니다.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "You have reached your API usage limits: ...",
    "details": { "error_code": "enforced_spend_limit_reached" }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

• 오류 유형은 속도 제한과 같은 rate_limit_error지만 retry-after 헤더가 없습니다. SDK의 자동 재시도도 접근이 다시 열릴 때까지 계속 실패합니다.
• 메시지 API에서는 error.details.error_code가 enforced_spend_limit_reached이므로 속도 제한과 구분할 수 있습니다.
• 더 높은 등급으로 올라가면 다시 쓸 수 있습니다.

직접 정하는 지출 한도

등급 상한보다 낮은 한도를 직접 정해 비용을 통제할 수도 있습니다. 문서가 안내하는 순서는 콘솔의 결제 페이지에서 지출 한도 항목을 열어 값을 조정하는 것이고, 값은 현재 등급의 상한을 넘을 수 없습니다.

• 직접 정한 한도에 닿으면 요청은 HTTP 400과 invalid_request_error를 받습니다. 메시지는 “You have reached your specified API usage limits”로 시작하고, 워크스페이스 한도라면 “specified workspace API usage limits”로 시작하며 접근이 다시 열리는 시점을 알려 줍니다.
• 한도를 올리거나 지우면 더 빨리 복구됩니다.
• 클로드 코드 워크스페이스의 한도는 따로 검사되어, 한도를 넘으면 retry-after가 붙은 429를 받을 수 있습니다.

같은 “한도 도달”이라도 등급 상한은 429, 직접 정한 한도는 400으로 나온다는 점이 구분 기준입니다.

속도 제한은 분당 세 가지로 잽니다

메시지 API의 속도 제한은 모델 계열마다 분당 요청 수(RPM), 분당 입력 토큰 수(ITPM), 분당 출력 토큰 수(OTPM)로 잽니다. 하나라도 넘으면 어떤 한도를 넘었는지 알려 주는 429를 받습니다. 응답에 retry-after 헤더가 있으면 그 초만큼 기다린 뒤 다시 시도합니다.

• 분당 60회 같은 한도는 실제로는 초당 1회처럼 더 짧은 간격으로 적용될 수 있어서, 짧은 시간에 몰린 요청은 한도 안에서도 429를 부를 수 있습니다.
• 한도는 토큰 버킷 방식으로 적용됩니다. 정해진 시각에 한꺼번에 초기화되지 않고, 용량이 최대치까지 계속 채워집니다.
• 문서가 밝히듯 이 수치는 보장되는 최소치가 아니라 최대 허용치입니다.

등급별 분당 한도 (일부 모델)

문서의 표에서 최신 모델 계열 몇 가지만 옮겼습니다. 단위는 RPM(요청), ITPM(입력 토큰), OTPM(출력 토큰)입니다.

모델	Start	Build	Scale
Claude Opus 5.5	1,000 / 2,000,000 / 400,000	5,000 / 5,000,000 / 1,000,000	10,000 / 10,000,000 / 2,000,000
Claude Sonnet 5.5	1,000 / 2,000,000 / 400,000	5,000 / 5,000,000 / 1,000,000	10,000 / 10,000,000 / 2,000,000
Claude Haiku 5.5	1,000 / 2,000,000 / 400,000	5,000 / 5,000,000 / 1,000,000	10,000 / 10,000,000 / 2,000,000
Claude Fable 5.x	1,000 / 500,000 / 100,000	2,000 / 1,500,000 / 300,000	4,000 / 4,000,000 / 800,000

문서가 단 주석도 있습니다. Fable 한도는 Claude Fable 5.1과 Claude Fable 5의 합산 트래픽에 한꺼번에 적용되고, Opus 5.5와 Opus 5는 각각 별도 한도를 가집니다. 이 표는 표준 한도이고, 신규 조직은 더 낮게 시작할 수 있으며, 실제 한도는 콘솔의 속도 제한 페이지가 기준입니다. 표의 수치는 시간이 지나면 바뀔 수 있습니다.

캐시된 입력은 입력 한도에서 빠집니다

공식 문서는 대부분의 클로드 모델에서 캐시에서 읽은 입력 토큰은 분당 입력 토큰 한도에 포함되지 않는다고 설명합니다. 한도에 들어가는 것은 다음 두 가지입니다.

• input_tokens: 마지막 캐시 지점 뒤의 토큰
• cache_creation_input_tokens: 캐시에 새로 쓰는 토큰

cache_read_input_tokens는 한도에 포함되지 않습니다. 문서의 예시는 분당 입력 토큰 한도가 2,000,000이고 캐시 적중률이 80%이면 실질적으로 분당 10,000,000 입력 토큰을 처리할 수 있다는 계산입니다. 총 입력 토큰은 세 값을 더한 값이고, 캐시된 문서가 크면 input_tokens가 총량보다 훨씬 작게 나옵니다. 문서는 Claude Haiku 3.5만 캐시 읽기 토큰도 입력 한도에 포함한다고 따로 적었습니다.

출력 토큰은 실제로 생성된 토큰만 실시간으로 세고, max_tokens 값은 출력 한도 계산에 영향을 주지 않는다고 문서가 설명합니다. 그래서 max_tokens를 크게 잡는다고 속도 제한 측면에서 손해를 보지는 않습니다.

응답 헤더 읽는 법

API 응답의 헤더는 적용된 한도, 현재 사용량, 초기화 시점을 알려 줍니다. 문서가 나열한 주요 헤더는 다음과 같습니다.

• retry-after: 다시 시도할 수 있기까지 기다릴 초. 이보다 빨리 보낸 요청은 실패합니다. 모든 429에 붙는 것은 아니고, 지출 한도 429에는 붙지 않습니다.
• anthropic-ratelimit-requests-limit, -remaining, -reset: 요청 수의 최대값, 남은 수, 한도가 완전히 채워지는 시각(RFC 3339 형식)
• anthropic-ratelimit-input-tokens-*, anthropic-ratelimit-output-tokens-*: 입력과 출력 토큰의 같은 세 가지 값. 남은 토큰은 천 단위로 반올림해 줍니다.
• anthropic-ratelimit-tokens-*: 현재 적용 중인 가장 엄격한 한도의 값. 워크스페이스 한도가 걸려 있으면 그 값이 나옵니다.
• anthropic-workspace-id: 요청이 어느 워크스페이스에 잡혔는지 알려 주는 ID

우선순위 계층 전용 헤더도 있지만 이 글에서는 다루지 않습니다.

급증할 때 나는 429

문서는 조직의 사용량이 갑자기 늘면 한도 안에서도 가속 제한 때문에 429가 날 수 있다고 경고합니다. 피하려면 트래픽을 천천히 늘리고 일정한 사용 패턴을 유지하라고 안내합니다. 새 서비스를 열면서 한꺼번에 요청을 쏟는 방식은 피하는 편이 안전합니다.

워크스페이스별로 더 낮게 제한하기

한 조직의 여러 워크스페이스 중 하나가 한도를 독차지하지 않도록 워크스페이스마다 지출 한도와 속도 제한을 따로 정할 수 있습니다. 문서의 예시는 조직 한도가 분당 입력 토큰 40,000인데 한 워크스페이스를 30,000으로 제한하는 경우입니다. 주의점은 다음과 같습니다.

• 기본 워크스페이스에는 한도를 설정할 수 없습니다.
• 설정하지 않으면 워크스페이스 한도는 조직 한도와 같습니다.
• 워크스페이스 한도는 요청, 입력 토큰, 출력 토큰처럼 종류별로 따로 정합니다.
• 워크스페이스 한도의 합이 더 커도 조직 전체 한도는 항상 적용됩니다.

배치, 파일, 에이전트 한도는 따로입니다

• Message Batches API: 모든 모델에 공통인 자체 한도가 있습니다. Start는 분당 요청 1,000과 처리 대기열 200,000건, Build는 2,000과 300,000건, Scale은 4,000과 500,000건이며, 한 배치당 최대 100,000건입니다.
• Managed Agents: 조직 단위로 생성 엔드포인트는 분당 300회, 조회 엔드포인트는 분당 1,200회이고 메시지 API와는 별개입니다.
• Files API: 업로드, 목록, 조회, 다운로드, 삭제가 합쳐진 자체 조직 한도가 있고 메시지 API와 별개입니다.
• 빠른 모드: Claude Opus 5.5 등에서 빠른 모드를 쓰면 표준 Opus와 별도의 전용 한도가 적용됩니다. Opus 5.5는 시작·빌드·스케일 등급에 기본 빠른 모드 한도가 있어 따로 신청하지 않아도 쓸 수 있다고 문서가 안내하고, 한도를 넘으면 retry-after가 붙은 429를 받습니다.

한도를 올리려면

더 높은 속도 제한이나 월 지출 상한이 필요하면 콘솔의 속도 제한 페이지에서 등급 상향을 요청하는 방법이 안내되어 있고, 급하면 지원 팀에 문의할 수 있다고 문서가 설명합니다. 현재 한도는 콘솔의 속도 제한 페이지나 속도 제한 API로 읽을 수 있고, 사용량 페이지에서는 입력·출력 토큰 한도 대비 사용량과 입력 토큰의 캐시 적중률을 차트로 볼 수 있습니다.

정리자의 판단: 429를 받았을 때 점검 순서

아래는 공식 문서의 내용을 바탕으로 정리한 해석이며, 문서에 그대로 적힌 문장은 아닙니다.

• 429가 오면 먼저 retry-after 헤더가 있는지, 응답에 enforced_spend_limit_reached 코드가 있는지를 구분하는 것이 순서입니다. 지출 한도 때문이라면 재시도는 소용이 없으므로, 재시도 로직이 이 경우에 무한히 반복되지 않게 막아 두는 편이 안전합니다.
• 같은 내용을 반복해서 보내는 요청은 프롬프트 캐싱으로 입력 한도 여유를 늘릴 수 있습니다. 문서는 대부분의 모델에서 캐시에서 읽은 토큰이 입력 한도에 잡히지 않는다고 설명합니다.
• 트래픽이 갑자기 늘어나는 작업은 한 번에 올리지 않고 점진적으로 늘리는 쪽이 가속 한도를 피하기 쉽습니다.
• 비용 상한이 중요하다면 등급의 월 한도보다 낮은 지출 한도를 직접 정해 두는 방법이 있습니다. 이 한도에 닿으면 429가 아니라 400 오류가 나므로, 오류 처리도 따로 구분해야 합니다.
• 일부 모델은 한도가 합산됩니다(예: Fable 5.1과 Fable 5, Opus 4.x 묶음). 같은 묶음 안에서 모델을 바꿔도 한도는 나눠 쓰게 됩니다.

자주 묻는 질문

429가 나면 무조건 기다리면 되나요?

속도 제한 429는 retry-after가 있으면 그만큼 기다리면 됩니다. 하지만 월 지출 한도 429는 retry-after가 없고 다음 달 1일 00:00(UTC)까지 계속 실패합니다. 오류 본문의 error_code가 enforced_spend_limit_reached인지 먼저 확인해야 합니다. 429 말고 다른 오류 코드가 났을 때의 확인 순서는 API 오류 코드 글에 정리했습니다.

캐시를 쓰면 한도가 정말 늘어나나요?

문서 기준으로 대부분의 모델에서 캐시 읽기 토큰은 입력 한도에서 빠지므로 같은 한도로 더 많은 입력을 처리할 수 있습니다. 캐시에 새로 쓰는 토큰은 한도에 포함됩니다.

max_tokens를 크게 잡으면 출력 한도에 걸리나요?

문서는 max_tokens가 출력 토큰 한도 계산에 들어가지 않고 실제로 생성된 토큰만 센다고 설명합니다.

직접 정한 한도와 등급 한도는 어떻게 구분하나요?

직접 정한 지출 한도에 닿으면 400의 invalid_request_error, 등급의 월 지출 상한에 닿으면 429의 rate_limit_error로 나옵니다.

표에 있는 수치는 지금도 같은가요?

2026년 10월 26일 문서의 표준 한도입니다. 모델 계열과 수치는 바뀔 수 있고, 신규 조직은 더 낮게 시작할 수 있으므로 실제 한도는 콘솔에서 확인해야 합니다.

함께 읽을 글입니다. 캐시로 입력 비용과 한도를 줄이는 방법은 프롬프트 캐싱 글에, 대량 요청을 절반 가격으로 처리하는 방법은 API 배치 처리 글에, 응답을 조각 단위로 받는 방법은 API 스트리밍 글에 정리했습니다.