Claude API의 429 rate_limit_error — 의미와 해결 방법

429는 "더 천천히"라는 오류이지 "돈이 부족하다"는 오류가 아닙니다. 차이가 중요합니다. 전자의 해결책은 기다리는 것이고 후자는 충전하는 것입니다. 두 가지를 혼동하면 잘못된 곳에서 몇 시간씩 디버깅하게 됩니다.

오류

resposta (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

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

원인	해결 방법
계정 한도를 초과한 분당 요청 수	한꺼번에 모두 전송하지 말고 클라이언트에서 요청을 대기열에 넣고 동시성을 제한하세요.
분당 토큰 수가 한도를 초과함	긴 프롬프트는 요청 수 한도보다 훨씬 먼저 토큰 할당량을 소모합니다. 컨텍스트를 줄이거나 작업을 나누세요.
여러 프로세스가 동일한 키를 사용함	한도는 프로세스가 아니라 키에 적용됩니다. 병렬 워커는 동일한 할당량에 합산됩니다.
백오프 없는 재시도	즉시 반복하면 계속 한도를 초과하게 됩니다. 지터가 포함된 지수 백오프는 필수입니다.

retry-after를 제공하면 반드시 준수하세요.

응답에 retry-after 헤더가 포함되어 있다면 이는 제안이 아니라 요청이 다시 승인되는 정확한 시점입니다. 그보다 짧게 기다리면 또 다른 429가 발생합니다.

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

원천에서 동시성을 제한하세요.

가장 흔한 원인은 전체량이 아니라 순간적인 폭주입니다. 같은 순간에 전송한 20개의 요청은 1분 동안 분산된 60개의 요청이 초과하지 않는 한도를 초과합니다. 세마포어는 재시도만으로 해결되지 않는 문제를 해결합니다.

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

속도 제한인지 잔액 부족인지 확인하세요.

429는 크레딧 부족을 의미하지 않습니다. 크레딧 부족은 402입니다. 로그에 두 오류가 섞여 있다면 조사하기 전에 상태 코드별로 분리하세요. 429의 해결책은 타이밍 조정이고, 402의 해결책은 충전입니다. 402를 반복하면 영원히 실패합니다.

Kunavo를 통해 호출하는 경우

Kunavo에서는 한도가 키별로 적용되고 잔액은 별도의 선불 지갑이므로 두 경우가 서로 다른 상태 코드로 나타납니다. 429는 속도 제한, 402는 잔액이 호출 비용을 충당하지 못하는 경우입니다. 한 오류가 다른 오류로 위장하는 일은 없습니다. 거부된 요청에는 요금이 부과되지 않습니다. 각 호출이 잔액에서 얼마나 차감되는지를 결정하는 토큰별 요금은 Claude API 가격 가이드.

자주 묻는 질문

429는 크레딧이 다 떨어졌다는 뜻인가요?

아니요. 잔액 부족은 402입니다. 429는 속도에 관한 오류입니다. 짧은 시간에 너무 많은 요청 또는 토큰을 보냈으므로 기다리면 해결됩니다.

얼마나 기다려야 하나요?

retry-after 헤더가 있으면 정확히 그 시간만큼 기다리세요. 없으면 1~2초부터 시작해 지터가 포함된 지수 백오프를 적용하고, 최대 30~60초까지 늘리세요.

한도를 늘리면 해결되나요?

실제 요청량이 매우 많다면 도움이 되지만, 대부분의 429는 짧은 순간의 폭주에서 발생합니다. 동시성을 제한하면 한도를 변경하지 않고도 해결되는 경우가 많습니다.