Claude API 429 rate_limit_error — 원인과 확실한 해결 방법

Claude API의 429는 Anthropic의 분당 한도인 요청 수, 입력 토큰 또는 출력 토큰 중 하나를 초과했다는 뜻입니다. 해결책은 대개 ‘더 오래 기다리기’가 아닙니다. retry-after를 준수하고, 지터가 있는 백오프를 추가하며, 급증을 완화해야 합니다. 전체 대응 방법은 다음과 같습니다.

오류

응답(HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

원인과 해결 방법 한눈에 보기

원인	해결 방법
분당 요청 수(RPM) 한도 초과	클라이언트 측에서 요청을 큐에 넣고, 재시도하기 전에 retry-after 헤더를 준수하세요.
분당 입력 토큰 수(ITPM) 초과 — 요청은 적지만 프롬프트가 큼	검색된 컨텍스트를 줄이고, 지원되는 요금제에서 프롬프트 캐싱을 활성화하여 캐시된 토큰이 한도에 포함되지 않게 하세요.
분당 출력 토큰 수(OTPM) 초과	max_tokens를 현실적으로 설정하세요 — 긴 생성에서는 OTPM이 가장 먼저 도달하는 한도인 경우가 많습니다.
트래픽 급증(크론이 :00에 모든 작업 실행)	스케줄에 지터를 추가하고 배치 작업을 1분 전체에 분산하세요.

재시도하기 전에 응답을 읽으세요

Anthropic은 기다려야 할 초를 담은 retry-after 헤더를 반환하며, 오류 메시지에는 초과한 한도가 표시됩니다. 이를 읽지 않고 즉시 재시도하면 단일 429가 429 폭풍으로 바뀝니다.

지터가 있는 지수 백오프를 추가하세요

재시도 가능한 상태(429, 500, 529)만 재시도하고, 인증 또는 검증 오류는 절대 재시도하지 마세요. 이 코드는 Anthropic에 직접 요청할 때나 OpenAI 호환 엔드포인트에서나 수정 없이 작동합니다:

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

요청 수가 아니라 토큰 수를 줄이세요

메시지가 토큰 한도를 언급한다면 백오프만으로는 해결되지 않습니다. 검색된 청크를 줄이고 max_tokens를 제한하며 프롬프트 캐싱을 켜세요 — 입력 비율의 10% 수준인 크고 안정적인 시스템 프롬프트도 ITPM 부담을 줄입니다.

Kunavo를 통해 호출하는 경우

Kunavo를 통해 Claude를 호출한다고 속도 제한이 사라지는 것은 아니지만 장애 비용은 달라집니다. 429를 포함한 실패한 요청에는 절대 요금이 부과되지 않으며, 키별 사용량 대시보드에서 어떤 키와 모델이 급증하고 있는지 정확히 확인해 완화할 수 있습니다. 위 백오프 코드는 그대로 사용할 수 있고 base_url만 다릅니다. 속도 제한은 가격이 아니라 처리량의 상한입니다 — Claude 호출의 실제 1M 토큰당 비용과 Anthropic의 공식 가격을 당사 가격과 함께 보려면 Anthropic Claude API 가격표.

자주 묻는 질문

Anthropic 등급을 올리면 429가 사라지나요?

상위 등급은 분당 한도를 높이므로 429가 드물어지지만, 어떤 고정 한도든 트래픽 급증으로 도달할 수 있습니다. 등급과 관계없이 프로덕션 코드는 백오프가 필요합니다.

429를 즉시 재시도해야 하나요?

아니요 — retry-after 헤더를 준수하세요. 헤더가 없으면 지터가 있는 지수 백오프를 사용하세요. 즉시 재시도하면 속도 제한 기간이 늘어나고 더 긴 차단으로 이어질 수 있습니다.

실패한 429 요청에도 비용이 드나요?

Anthropic은 거부된 요청에 요금을 부과하지 않으며 Kunavo도 마찬가지입니다 — 실패한 요청에는 절대 요금이 부과되지 않습니다. 429의 비용은 금액이 아니라 지연 시간입니다.