■ rate limit

rate limits : RPM · ITPM · OTPM · 429 · 헤더3.4 본편

표시가 없는 문장은 공식 문서에서 확인한 내용이에요. 다른 표시는 읽는 법

왜 배우나 — 시험이 요구하는 것

시험 목표 3.4 대규모 관측 · D3 연결 19%
Analyze observability challenges and select monitoring strategies at scale

이 개념으로 푸는 판단 (할 수 있어야 하는 것)

3.4③ 트래픽이 늘자 429 가 난다 — 무엇을 보고, 캐싱이 도움이 되나? — 속도 제한 관측·대응 (응답 헤더 · 캐시 인지 ITPM)
3.3② 매시 쌓인 티켓 5,000건을 15분 안에 분류해 큐로 보내야 한다 — Batch API 로 보내나? — 동기 호출 vs Batch API (완료 시각 약속이 필요한가)
7.3③ API 오류가 쏟아질 때 무엇부터 보나? — 오류 종류별 대응 (재시도할 것 / 한도를 볼 것 / 오류가 아닌 것)

한눈에

Messages API rate limit(속도 제한)은 모델 클래스별로 셋이다

분당 요청(RPM)
분당 입력 토큰(ITPM)
분당 출력 토큰(OTPM)

하나라도 넘으면 429 가 온다. 응답에는 어느 한도인지와 retry-after(몇 초 기다릴지)가 담긴다

한도는 조직 단위로, 사용량 티어(Start · Build · Scale · Custom)에 따라 정해진다. 보장된 최소가 아니라 허용 최대치다

비유 API 게이트웨이 스로틀링과 같다. 토큰 버킷, X-RateLimit-Remaining·Retry-After 헤더가 있다. CDN 적중은 오리진 한도를 안 먹는다

분당 요청(RPM)·입력 토큰(ITPM)·출력 토큰(OTPM) 세 한도 중 하나라도 넘으면 429 와 retry-after 가 오고, 캐시 읽은 입력은 대부분 ITPM 에 안 세며 짧은 폭주도 걸린다는 그림. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게)

ELI5

놀이공원 입장 줄을 생각해 보세요.

1분에 들어갈 수 있는 사람 수가 정해져 있어요.
한꺼번에 몰려오면 1분 한도 안이어도 입구에서 잠깐 막혀요.
입구는 "몇 초 뒤에 오세요"라고 알려 줘요.
연간 회원(미리 받아 둔 표)은 줄 수를 안 세요.
그런데 이번 달 예산을 다 쓰면 기다려도 다음 달까지 못 들어가요.

개념 설명

영상 — 429, 재시도를 늘리면 풀릴까? (약 43초 · 소리 없음 · 자막). 통 수위 · 1초 이른 재시도 · 늘린 재시도 횟수는 그림용 가정 작은 화면에서는 전체화면(⛶)으로 보세요.

원리

세 한도 (모델 클래스별)

한도는 RPM(분당 요청) · ITPM(분당 입력 토큰) · OTPM(분당 출력 토큰) 셋이다. 하나라도 넘으면 429 가 온다. 응답에는 어느 한도인지와 retry-after 가 담긴다.
한도는 조직 단위다. 사용량 티어(Start · Build · Scale · Custom)로 정해지고, 쓰다 보면 올라간다. 한도는 최대치일 뿐 보장이 아니다.

토큰 버킷

버킷은 고정 간격으로 리셋되지 않고 계속 채워진다. 그래서 분당 한도가 초 단위로 걸릴 수 있다. 짧은 폭주가 한도 안에서도 429 를 낸다.

무엇을 세나

ITPM : 캐시 안 된 입력과 캐시 쓰기를 센다. 대부분 모델에서 캐시 읽기는 세지 않는다. 그래서 캐싱이 한도를 사실상 넓힌다 (■ 프롬프트 캐싱 · 규칙 ④).
OTPM : 실제 생성한 출력만 센다. max_tokens 값은 세지 않는다.
한도는 모델마다 따로다. 그래서 다른 모델은 각자 한도까지 동시에 쓴다.

429 의 두 얼굴

rate limit 429 : retry-after 가 있다. 기다렸다 재시도한다.
지출 상한 429 : retry-after 가 없고 error_code: enforced_spend_limit_reached 가 찍힌다. 다음 달 1일 00:00 UTC 까지 재시도해도 실패한다.
내가 건 지출 한도는 400 이다. API 과부하는 529 다(내 한도 문제가 아니다).

재시도

공식 SDK 가 연결 오류 · 429 · 5xx 를 지수 백오프로 기본 2번 자동 재시도하고 retry-after 를 따른다.

규칙과 판단

429 에 retry-after 가 있으면 한도 초과라 기다렸다 재시도, 없으면 월 지출 상한이라 재시도가 무의미하고, 400 은 내가 건 지출 한도, 529 는 일시 과부하라는 결정 나무. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게)

갈림길

③⑤ 오류 가르기 [3.4③]

상태 코드가 무엇인가?

429

retry-after 있나?

예

rate limit 초과

기다렸다 재시도한다. 캐싱, 폭주 평탄화, 상향 요청도 쓴다

아니오

티어 월 지출 상한 도달

enforced_spend_limit_reached 다. 재시도는 무의미하다(SDK 재시도도 실패). 상향을 요청한다

400

내가 건 지출 한도 도달

invalid_request_error "…specified API usage limits" 다. 한도를 올리거나 지운다

529

API 일시 과부하

내 한도 문제가 아니다. 백오프로 재시도한다

④⑥ 한도 넓히기 [3.4③] [3.3②]

상황이 어떤가?

같은 입력 반복

캐싱

대부분 모델에서 캐시 읽은 입력은 ITPM 에 세지 않는다

max_tokens 를 크게 잡을까 걱정된다

한도 불이익이 없다

OTPM 은 실제 생성분만 센다. 그래서 max_tokens 를 크게 잡아도 한도 불이익이 없다

여러 모델을 쓸 수 있다

모델마다 따로

다른 모델은 각자 한도까지 동시에 쓴다

한 팀이 폭주한다

워크스페이스별 한도

워크스페이스별로 더 낮은 한도를 건다. 그러면 한 팀 폭주가 다른 팀 몫까지 막지 않는다

흐름

그림 속 이름·금액·시간·토큰 수는 예시예요. 공식 한도·동작은 카드 본문 값이 기준.

장면 글로 보기

칸 : 앱 → 한도 → API

규칙 (한도) : 버킷은 계속 채워짐(고정 간격 리셋 아님)

질문 : 429 가 오면 늘 기다렸다 다시 보내면 될까?

① 짧은 폭주 ≠

시작 : 앱 — 쪽지 : RPM 한도 60 / 이번 분 20개뿐
요청 : 앱 → 한도 : 짧게 몰아서 보낸다 — 쪽지 : 요청 20개가 / 같은 1초에
거절 : 한도 : 429 와 retry-after 를 준다 — 쪽지 : 429 · 요청 한도 초과 / retry-after: 3
끝 : 분당 60이 초당 1로 걸릴 수 있다. 분당 한도 안이어도 짧은 폭주는 429 를 받는다

② 백오프 재시도 ✓

시작 : 앱 — 쪽지 : 요청 20개 대기 중
요청 : 앱 → 한도 : 요청을 보낸다 — 쪽지 : POST /v1/messages
거절 : 한도 : 429 와 retry-after 를 준다 — 쪽지 : 429 · 요청 한도 초과 / retry-after: 3
타이머 : 앱 : retry-after(몇 초 기다릴지)
재시도 : 앱 → API : 지수 백오프로 retry-after 를 따른다 — 쪽지 : 3초 뒤 재요청 / 200 OK
끝 : 공식 SDK 는 429 · 5xx · 연결 오류를 지수 백오프로 기본 2번 자동 재시도한다

③ 지출 상한 429 ≠

시작 : 앱 — 쪽지 : 요청 / 9월 15일 14:00
요청 : 앱 → 한도 : 요청을 보낸다 — 쪽지 : POST /v1/messages
거절 : 한도 : retry-after 가 없다 — 쪽지 : 429 · retry-after 없음 / error_code: enforced_ / spend_limit_reached
재시도 : 앱 → 한도 : 재시도는 무의미하다(SDK 재시도도 실패) — 쪽지 : 재시도 2번 / → 또 429
끝 : 티어 월 지출 상한에 닿았다. 다음 달 1일 00:00 UTC 까지 멈춘다. 재시도로는 못 푼다

나머지 규칙

버킷은 계속 채워진다(고정 간격 리셋이 아니다). 그래서 분당 60이 초당 1로 걸릴 수 있다. 짧은 폭주가 429 를 낸다
무엇을 보나 : 응답 헤더 anthropic-ratelimit-{requests|tokens|input-tokens|output-tokens}-{limit|remaining|reset} 와 retry-after 를 본다. tokens-* 는 지금 가장 빡빡한 한도 값이다(워크스페이스 한도에 걸렸으면 그 값) [3.4③]

추세는 Console Usage 의 Rate Limit 차트로 본다 (캐시 안 된 분당 입력 최대치 · 한도 · 캐시 비율)
배치와 fast mode 는 한도가 따로다 (배치 = 배치 API RPM + 처리 대기열 요청 수)

규칙 원문 ③④⑤⑥ (갈림길로 그린 규칙)

재시도 : retry-after 보다 일찍 다시 보내면 또 실패한다. 공식 SDK 는 429 · 5xx · 연결 오류를 지수 백오프로 기본 2번 자동 재시도하고 retry-after 를 따른다 (max_retries 로 조정)
한도를 사실상 넓히기 : 대부분 모델에서 캐시 읽은 입력은 ITPM 에 세지 않는다. 그래서 캐싱한다. 계산과 예는 ■ 프롬프트 캐싱 · 규칙 ④ 에 있다

예외는 Haiku 3.5 다. 캐시 읽기도 ITPM 에 센다

OTPM 은 실제 생성분만 센다. 그래서 max_tokens 를 크게 잡아도 한도 불이익이 없다

한도는 모델마다 따로다. 그래서 다른 모델은 각자 한도까지 동시에 쓴다

429 계열을 가른다

증상	뜻	처방
429 + `retry-after`	rate limit 초과	기다렸다 재시도 · 캐싱 · 폭주 평탄화 · 상향 요청
429, `retry-after` 없음 · `error_code: enforced_spend_limit_reached`	티어 월 지출 상한에 닿았다. 다음 달 1일 00:00 UTC 까지 멈춘다	재시도는 무의미하다(SDK 재시도도 실패). 상향을 요청한다
400 `invalid_request_error` "…specified API usage limits"	내가 건 지출 한도에 닿았다	한도를 올리거나 지운다
529 `overloaded_error`	API 일시 과부하다 (내 한도 문제가 아니다)	백오프로 재시도한다

조직 안에서 나눠 쓰기 : 워크스페이스별로 더 낮은 한도(RPM · ITPM · OTPM 따로)를 건다. 그러면 한 팀의 폭주가 다른 팀 몫까지 잠식하지 않는다. 조직 한도는 늘 적용된다. 기본 워크스페이스에는 걸 수 없다

더 깊이 : 판단 규칙 · 상황 변수 (설명)

판단 규칙

조건	답	근거
429 가 났다. 어느 한도인지 알아야 한다	오류 본문(어느 한도)과 `retry-after`, `anthropic-ratelimit-*` 헤더를 본다	rate-limits
반복되는 긴 앞부분 때문에 ITPM 429 가 난다	캐싱한다 (캐시 읽기는 대부분 ITPM 에 세지 않는다)	rate-limits
429 인데 `retry-after` 가 없다	지출 상한인지 `error_code` 로 확인한다. 재시도는 무의미하다. 상향을 요청한다	rate-limits
400 "…specified API usage limits" 가 났다	내가 건 지출 한도다. 한도를 조정한다	rate-limits
529 가 났다	일시 과부하다. 백오프로 재시도한다 (한도 상향이 아니다)	errors
한 팀이 조직 한도를 다 먹는다	워크스페이스별로 더 낮은 한도를 건다	rate-limits
한도 안인데 가끔 429 가 난다	요청을 고르게 흘린다 (짧은 폭주)	rate-limits
여유가 얼마나 남았나, 무엇을 올려 달라 할지 알고 싶다	Console Usage 의 Rate Limit 차트를 본다	rate-limits
한도를 코드로 읽어야 한다	Rate Limits API 를 쓴다	rate-limits

상황 변수

변수	값	답 쪽	등급	근거
막힌 한도	ITPM · 앞부분 반복	캐싱이 가장 먼저다		rate-limits
막힌 한도	OTPM	캐싱은 효과가 없다. 출력 줄이기 · 상향 · 모델 분산을 쓴다	계산	뒤집히는 때 2
막힌 한도	RPM · 폭주	평탄화 · 큐		rate-limits
429 종류	`retry-after` 가 있다	기다렸다 재시도한다		rate-limits
429 종류	`retry-after` 가 없고 spend cap 코드가 있다	재시도하지 않는다. 상향을 요청한다		rate-limits
모델	캐시 읽기도 ITPM 에 세는 예외 모델이다	캐싱으로 한도 이득이 없다		rate-limits (각주 4). 어느 모델인지는 미해결 2
모델 수	쉬운 요청을 다른 모델로 보낸다	그 모델의 따로 된 한도를 쓴다		rate-limits
경로	Message Batches	배치 전용 한도(API RPM · 대기열 요청 수)가 있다		rate-limits
경로	fast mode	전용 한도가 있다. 429 와 `retry-after` 를 준다		rate-limits

연습 문제

월 중순부터 모든 요청이 429 로 실패한다429. 응답에는 retry-after 헤더가 없고retry-after 없음 error_code: enforced_spend_limit_reached 가 찍혀 있다. 개발자는 SDK 재시도 횟수를 늘리자고 한다. 무엇이 문제이고 무엇을 할까?

시험 대비

함정

"캐시 입력도 ITPM 을 똑같이 먹으니 한도 상향만 한다" 는 함정이다. 사실은 반대다. 대부분 모델에서 캐시 읽은 입력은 ITPM 에 세지 않는다 (■ 프롬프트 캐싱)
"429 면 무조건 재시도한다" 는 함정이다. 지출 상한 429 는 재시도해도 계속 실패한다
"max_tokens 를 크게 잡으면 OTPM 을 미리 먹는다" 는 함정이다. OTPM 은 실제 생성분만 센다
"분당 한도 안이면 안전하다" 는 함정이다. 초 단위 폭주로도 걸린다
529 를 내 한도 문제로 보고 상향을 요청하는 것은 함정이다. 이것은 과부하라 한도와 무관하다
"한도만큼은 보장된다" 는 함정이다. 한도는 최대치일 뿐이다

신호

"describing which rate limit was exceeded, along with a retry-after header indicating how long to wait."

"For most Claude models, only uncached input tokens count toward your ITPM rate limits."

"With effective caching, you can substantially increase your actual throughput without raising your rate limits."

"Short bursts of requests can exceed the limit and trigger rate limit errors."

"Retrying, including the SDKs' automatic retries, fails until access resumes."

"The max_tokens parameter does not factor into OTPM rate limit calculations"

보통은 429 면 retry-after 대로 재시도하지만, 지출 상한이면 재시도가 헛수고라 상향 요청, 분당 한도 안의 429 는 고르게 퍼뜨리고, OTPM 이 막히면 출력을 줄인다. — 그림으로 보기 (AI 생성 · Codex · 누르면 크게) — 자세한 조건은 아래 '더 깊이'에 있어요

더 깊이 : 뒤집히는 때 · 오답 재료 (설명)

뒤집히는 때

1. 캐싱이 ITPM 을 얼마나 넓히나 (새 숫자)

조건 : ITPM 한도가 50만이다(가정). 요청당 입력 6,000 토큰 중 5,000 이 매번 캐시 읽기다.
계산 : 캐싱이 없으면 요청당 6,000 이라 분당 약 83 요청이다. 캐시 적중이면 ITPM 에 1,000 만 센다. 그래서 분당 500 요청이다 (6배).
전제 : 대부분 모델 기준이다(각주 4 예외 아님). 캐시 쓰기 요청(ITPM 에 셈)은 드물다. RPM · OTPM 은 안 막힌다.
등급 : 계산 (셈 규칙은 확인)
근거 : rate-limits

2. 캐싱이 안 듣는 때 — OTPM 이 먼저 막힘

조건 : OTPM 한도가 8만이다(가정). 응답은 평균 800 토큰이다.
계산 : 80,000 ÷ 800 = 분당 100 요청이 상한이다. 입력 캐싱을 아무리 해도 출력은 그대로라 이 벽은 안 움직인다.
처방 : 출력을 줄인다(■ 지연 줄이기 lever · 규칙 ③). 상향을 요청한다. 쉬운 요청을 다른 모델(따로 된 한도)로 보낸다. max_tokens 를 줄이는 것은 OTPM 셈과 무관하다(실제 생성분만 셈).
등급 : 계산 (OTPM 규칙은 확인)
근거 : rate-limits

3. 분당 한도 안인데 429 가 나는 때

조건 : RPM 한도는 120 이다. 매 분 정각에 요청 40개를 한꺼번에 보낸다.
계산 : 분당 40 < 120 이다. 그래도 공식 예처럼 분당 한도가 초 단위로 적용되면 120 RPM ≈ 초당 2 다. 그래서 한 순간 40개는 넘친다.
처방 : 요청을 1분에 고르게 퍼뜨린다. 큐를 쓴다. retry-after 를 따른다.
전제 : 초 단위 환산은 문서 예시(60 RPM 이면 초당 1)와 같은 비례라고 가정한다.
등급 : 계산 (폭주 규칙은 확인)
근거 : rate-limits

4. 재시도가 답이 아닌 때 — 지출 상한

조건 : Start 티어(월 $500) 조직이 월 중순에 상한에 닿았다. 429 가 계속 난다.
판단 : retry-after 가 없고 enforced_spend_limit_reached 가 찍힌다. 그래서 다음 달 1일 00:00 UTC(한국 시각 09:00)까지 SDK 자동 재시도도 전부 실패한다. 재시도 로직을 늘리는 것은 헛수고다. 상향을 요청하거나(Rate limits 페이지) 지원팀에 연락한다.
등급 : (UTC 를 KST 로 바꾼 환산은 계산)
근거 : rate-limits

5. 한도 상향이 맞는 때

조건 : 캐싱 적중률이 이미 높다(Usage 차트의 캐시 비율). 요청이 고르게 흐른다. 그런데도 캐시 안 된 입력·출력이 한도에 붙어 있다.
판단 : 그때는 상향 요청이 정답이다. "상향 요청은 항상 오답"도 틀리다.
근거 : rate-limits

오답 재료

오답	왜 끌리나	왜 틀리나	근거
"캐시된 입력도 ITPM 을 똑같이 먹으니 캐싱은 rate limit(속도 제한)엔 소용없다. 한도 상향만"	많은 제공자는 TPM 에 전부 센다	대부분 Claude 모델은 캐시 안 된 입력만 ITPM 에 센다	rate-limits
"429 면 무조건 지수 백오프로 재시도"	SDK 가 그렇게 한다	지출 상한 429 는 재시도해도 계속 실패한다	rate-limits
"`max_tokens` 를 크게 잡으면 OTPM 을 미리 차지한다"	예약처럼 느껴진다	실제 생성된 토큰만 센다	rate-limits
"분당 한도 안이면 429 가 안 난다"	분당 숫자만 본다	토큰 버킷이라 짧은 폭주로도 걸린다	rate-limits
"529 가 나니 한도 상향을 요청"	둘 다 '너무 많다' 류다	529 는 API 과부하다. 내 한도와 무관하다	errors
"한도는 이만큼 처리를 보장한다"	숫자가 계약처럼 보인다	최대치일 뿐 보장된 최소가 아니다	rate-limits
"워크스페이스 한도를 합쳐 조직 한도보다 크게 잡으면 더 쓸 수 있다"	합이 크니까	조직 한도는 항상 적용된다	rate-limits

참고

함께 보기

더 깊이 : 출처 · 상태 · 미해결 (참고)

출처

가이드 목표 3.4 공식 시험 가이드 v1.0
rate-limits
errors
릴리스 노트 (티어 3개 통합 2026-06-26)

상태

모든 줄을 공식 문서에서 확인

미해결

티어별 RPM · ITPM · OTPM 숫자 : rate-limits 원문의 한도 표가 받은 파일(ko·en)에 빠져 있다 (defuddle 이 표를 못 옮겼다, 검색어 "<table>"·"| Model" 0건). 숫자는 이 카드에 넣지 않았다.
각주 4("이 제한은 cache_read_input_tokens 를 ITPM 사용량에 포함")가 붙은 모델이 어느 것인지 같은 이유로 확인하지 못했다. 캐싱 카드의 "대부분 모델"과 같은 수준으로만 쓴다.
티어 통합(Start · Build · Scale, 2026-06-26)은 시험 가이드(2026-07) 직전에 바뀌었다. 시험이 옛 티어 이름(1~4)으로 물을 가능성이 있다(추론).