3가지 유형의 429
HTTP 429는 표준 "너무 많은 요청" 상태입니다. 여기서는 세 가지 상황을 포괄하며, JSON 오류 본문이 어떤 상황인지 알려줍니다.
| 오류 코드 | 의미 | 일반적인 해결책 |
|---|---|---|
rate_limited | 분당 요청 수 초과 | 요청 속도를 줄이고 분당 요청을 분산하세요 |
concurrency | 동시에 실행되는 요청이 너무 많음 | 동시성을 낮추고 슬롯이 비워지기를 기다리세요 |
과부하: Retry-After: 5 | 서비스의 일시적 부하, 사용자 탓 아님 | 헤더의 초수만큼 기다린 후 재시도하세요 |
원인을 먼저 확인하세요. 한 원인에 대한 해결책이 다른 원인에는 효과가 없습니다. 실제 문제가 20개의 워커가 동시에 실행하는 것이라면 분당 요청을 절반으로 줄여도 소용이 없습니다.
한도 확인
한도는 키 유형에 따라 다릅니다:
- 전체 키: 8개의 동시 요청 및 분당 300개의 요청.
- 시험 키: 2개의 동시 요청 및 분당 60개의 요청.
모든 응답에는 X-RateLimit-Limit-Requests 및 X-RateLimit-Limit-Concurrency 헤더가 포함되어 있어 클라이언트가 하드 코딩 없이 한도 값을 확인할 수 있습니다. 신규 사용자에게는 trial 키가 흔히 문제가 됩니다: 1회 요청 시 잘 작동하던 스크립트는 4개의 스레드 풀을 추가하면 실패하기 시작합니다. trial은 테스트용으로 제공되며, $20 이상의 충전 시 일반 키로 업그레이드할 수 있습니다(금액 및 보너스는 가격 책정 페이지를 참조하세요).
위의 숫자는 키별 기준입니다. 하나의 키를 웹 앱, 크론 작업, 동료의 노트북이 공유하면 모두 동일한 풀에서 사용하므로, 세 가지 작업량을 합산하기 전까지 429 오류가 무작위로 보입니다.
스트리밍이 동시성 오류를 더 자주 만드는 이유
일반 요청은 1~2초 동안 동시성 슬롯을 점유합니다. 스트리밍 요청(stream: true)은 마지막 토큰이 도착하고 스트림이 닫힐 때까지 슬롯을 점유합니다. 긴 응답은 수십 초 동안 슬롯을 점유하므로, 여러 활성 사용자가 있는 채팅 앱에서는 8개의 슬롯이 빠르게 고갈됩니다.
두 가지 실수가 대부분의 문제를 일으킵니다. 첫 번째는 스트림을 닫지 않고 중단하는 것입니다. 클라이언트가 읽기를 멈추고 연결을 열어두면 연결이 끝날 때까지 슬롯이 점유됩니다. finally 블록에서 응답을 닫거나 SDK의 컨텍스트 관리자를 사용하세요. 두 번째는 스트림 재시도 중 첫 스트림이 살아있는 동안 두 번째 스트림을 열어 슬롯 사용량을 두 배로 만드는 것입니다.
앱에서 키가 허용하는 것보다 더 많은 동시 긴 스트림이 필요한 경우, 클라이언트 측에서 새 채팅을 큐에 넣고 짧은 대기 상태를 표시하세요. 이는 사용자가 원시 오류를 보는 것보다 낫습니다.
백오프 Python 재시도 코드
이 패턴은 간단합니다: 429 오류를 잡고 코드를 읽은 후, 증가하는 지연 시간과 약간의 무작위 지연을 두고 다시 시도한 후 몇 번의 시도 후 포기합니다. 이 버전은 서비스의 Base URL을 대상으로 공식 openai 패키지를 사용합니다:
import random
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
max_retries=0, # we handle retries ourselves
)
def chat(messages, attempts=5):
for i in range(attempts):
try:
r = client.chat.completions.create(
model="uncensored",
messages=messages,
)
return r.choices[0].message.content
except RateLimitError as e:
headers = e.response.headers
wait = float(headers.get("Retry-After", 0))
if not wait:
wait = min(30, 2 ** i) # 1, 2, 4, 8, 16 seconds
wait += random.uniform(0, 1) # jitter
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(chat([{"role": "user", "content": "Reply with the word ok."}]))
헤더가 있는 경우 이를 최소 대기 시간으로 사용하세요. 헤더가 없으면 지수 지연이 rate_limited에 효과적입니다. 분당 윈도우가 계속 이동하기 때문입니다. 지터는 많은 워커가 동시에 재시도하는 것을 방지합니다.
동시 호출을 제한해 429 오류를 거의 방지하세요
재시도는 증상을 치료합니다. 세마포어는 슬롯 수보다 더 많은 요청을 보내지 않음으로써 대부분의 오류를 방지합니다. 재시도나 우발적인 요청이 여전히 여유를 가질 수 있도록 한도보다 약간 낮게 설정하세요:
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6) # full key allows 8; use 1 on a trial key
async def ask(prompt):
async with sem:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main():
prompts = [f"Give one fact about the number {n}." for n in range(50)]
results = await asyncio.gather(*(ask(p) for p in prompts))
print(len(results))
asyncio.run(main())
분당 300개 요청은 평균 초당 5개입니다. 짧은 작업을 대량으로 처리할 때 세마포어 앞에 작은 sleep이나 토큰 버킷을 추가하세요. SDK는 기본적으로 자체적으로 재시도하므로 max_retries을 명시적으로 설정하여 로직이 중첩되지 않게 하세요.
curl로 429 오류 재현 및 검사
코드를 변경하기 전에 원시 응답을 확인하세요. 헤더를 출력하려면 curl에 -i를 추가하고, 의도적으로 오류를 발생시키기 위해 몇 가지 요청을 병렬로 실행하세요:
for i in 1 2 3 4; do
curl -i -s https://api.onekeyllmapi.com/v1/chat/completions -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait
동시 2개 요청만 허용하는 체험 키에서는 세 번째 및 네 번째 호출이 상태 429와 오류 코드 concurrency로 반환되어야 합니다. 일반 키에서는 동시에 8개보다 더 많은 요청이 필요합니다. 각 응답에서 세 가지 사항을 확인하세요: 상태 줄, 존재하는 경우 Retry-After 헤더, JSON 본문의 error.code 필드. 이 작은 실험은 1시간의 추측보다 더 많은 것을 알려주며, 문제가 있는 경우 지원에 보여줄 수 있는 재현 가능한 사례를 제공합니다.
주변이 아닌 이를 위해 설계하세요
429를 타임아웃과 같은 정상적인 이벤트로 취급하세요. 모델 호출을 하나의 함수 뒤에 배치하고, 이유를 기록해 모든 재시도를 로깅하며, 재시도율이 높아질 때 알 수 있도록 카운터를 노출하세요. 상승하는 재시도율은 사용자가 불평하기 훨씬 전에 트래픽이 단일 키의 한도를 초과했음을 나타내는 초기 신호입니다. 채팅 제품의 경우 사용자별 작은 인메모리 큐를 사용하면 한 명의 사용자가 다른 모든 사용자의 8개 슬롯을 모두 차지하는 것을 방지할 수 있습니다.
간단한 디버깅 체크리스트
- 각 429 오류에 대해 전체 오류 본문과
X-Request-Id헤더를 로깅하세요. code 필드는rate_limited과concurrency를 구분합니다. - 키가 체험 키인지 확인하세요. 해당 경우 분당 60회, 동시 2개 요청을 예상하세요.
- 실패한 프로그램뿐만 아니라 키를 사용하는 모든 프로그램을 세세요.
- 닫히지 않은 스트림과 지연 없이 즉시 재시도하는 루프를 찾으세요. 즉시 재시도 루프는 하나의 429 오류를 100개로 만듭니다.
X-Balance-USD또는GET /v1/balance로 잔액을 확인하세요. 잔액이 없는 것은 429 오류와 다른 문제이지만 확인하는 데 몇 초만 걸립니다.
실패한 요청은 요금이 부과되지 않으므로 재시도해도 거부된 시도에는 토큰 비용이 들지 않습니다. 상태 코드 및 헤더의 전체 목록은 문서을 참조하세요. 체험 키보다 높은 한도가 있는 키가 필요하면 API 키를 얻으세요 및 충전하세요.
