KO ▾
API 키 받기

LLM API 429 오류: 원인 및 해결 방법

LLM API 429 오류는 서버가 현재 요청을 거부한다는 뜻이지, 영구적인 거부라는 뜻이 아닙니다. 이 API에는 세 가지 명확한 원인이 있으며, 각각에 약간씩 다른 해결책이 필요합니다.

업데이트

8개의 차선이 있는 게이트에서 대기열에 있는 빛의 패킷, API 속도 제한을 나타냄

주요 포인트

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개 슬롯을 모두 차지하는 것을 방지할 수 있습니다.

간단한 디버깅 체크리스트

  1. 각 429 오류에 대해 전체 오류 본문과 X-Request-Id 헤더를 로깅하세요. code 필드는 rate_limited과 concurrency를 구분합니다.
  2. 키가 체험 키인지 확인하세요. 해당 경우 분당 60회, 동시 2개 요청을 예상하세요.
  3. 실패한 프로그램뿐만 아니라 키를 사용하는 모든 프로그램을 세세요.
  4. 닫히지 않은 스트림과 지연 없이 즉시 재시도하는 루프를 찾으세요. 즉시 재시도 루프는 하나의 429 오류를 100개로 만듭니다.
  5. X-Balance-USD 또는 GET /v1/balance로 잔액을 확인하세요. 잔액이 없는 것은 429 오류와 다른 문제이지만 확인하는 데 몇 초만 걸립니다.

실패한 요청은 요금이 부과되지 않으므로 재시도해도 거부된 시도에는 토큰 비용이 들지 않습니다. 상태 코드 및 헤더의 전체 목록은 문서을 참조하세요. 체험 키보다 높은 한도가 있는 키가 필요하면 API 키를 얻으세요 및 충전하세요.

질문과 답변

429 오류는 제 탓인가요, 아니면 제공업체 탓인가요?

둘 다 가능합니다. rate_limited 및 concurrency 코드는 키가 한도를 초과했음을 의미합니다. Retry-After 헤더가 있는 429는 일시적 과부하로 인해 발생할 수도 있으며, 명시된 시간 후 재시도하는 것이 올바른 대응입니다.

재시도 전에 얼마나 기다려야 합니까?

응답에 Retry-After 헤더가 있으면 해당 초수만큼 기다리세요. 그렇지 않으면 1초부터 시작해 매번 지연 시간을 두 배로 늘리고 약간의 랜덤 지터를 추가하세요.

거부된 요청에 비용이 발생하나요?

아닙니다. 실패하거나 거부된 요청에는 요금이 부과되지 않습니다.

한도를 늘릴 수 있나요?

전체 키는 8개의 동시 요청과 분당 300개 요청을 허용하며, 체험 키는 각각 2개와 60개입니다. 그 이상은 클라이언트 측의 큐를 통해 작업을 분산하세요.

키는 양식 하나만 작성하면 받을 수 있습니다

계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.