BroadRouter

LLM API 429 오류 처리 방법: 백오프, 지터, 동시 처리 제한

BroadNet Inference 팀 · 5분 분량 · 게시 · 업데이트

429는 요청 속도, 동시 처리, 지출 중 하나의 한도에 걸렸다는 뜻입니다. 상한을 둔 지수 백오프와 무작위 지터로 재시도하고, Retry-After가 오면 따르세요. 그다음 대부분의 429를 예방하세요. 세마포어로 동시 요청 수를 키의 한도에 맞추고 나머지는 큐에 넣습니다. 5xx도 같은 방식으로 재시도하고, 다른 4xx 오류는 요청을 고치세요.

429는 트래픽이 속도 제한을 넘었다는 뜻입니다. 분당 요청 수, 동시 요청 수, 분당 토큰 수, 지출 중 하나입니다. 해결은 두 부분으로 나뉩니다. 제대로 재시도하기: 상한을 둔 지수 백오프에 무작위 지터를 더하고 Retry-After를 따릅니다. 한꺼번에 덜 보내기: 키의 동시 요청 한도에 맞춘 세마포어와 큐를 씁니다. 아래에서 코드와 함께 둘 다 다룹니다.

전체 상태 코드 레퍼런스는 오류와 재시도 가이드를, 체크포인트와 타임아웃이 있는 몇 시간짜리 에이전트 실행은 장시간 실행 에이전트: 타임아웃과 재시도를 참고하세요.

429와 5xx는 무엇이 다른가요?

상태 누구의 문제인가 재시도? 방법
429 트래픽이 한도를 넘음 예 지터를 둔 백오프, Retry-After 준수, 동시 처리 줄이기
500 / 502 / 503 / 504 서버 쪽 예 상한을 둔 지수 백오프
연결 재설정, 타임아웃 네트워크 또는 서버 대개 예 백오프. 스트림은 새로 과금되어도 괜찮을 때만
400 / 422 잘못된 요청 아니요 페이로드 수정
401 / 402 / 403 키, 잔액 또는 정책 아니요 키 수정, 계정 충전, 허용 목록 수정
413 요청이 너무 큼 아니요 크기 줄이기

BroadNet Inference에서 429는 요청 속도, 동시 처리, 토큰 속도, 지출이라는 네 가지 한도 중 어느 것이든 뜻할 수 있습니다. 지출 한도는 30초 기다린다고 풀리지 않습니다. BroadNet 문서에는 오류 본문의 어느 필드가 어떤 한도인지 나와 있지 않으므로, 본문을 기록해 두고 키 세부 정보에 표시된 한도와 비교하세요.

공개 데이터셋 LLM API 무료 티어와 속도 제한은 제공업체 14곳이 무료 이용, 시작 속도 제한, 카드 등록 요구, 무료 티어 데이터의 학습 사용에 대해 공개한 내용을 값마다 출처와 날짜를 달아 비교합니다.

어떤 한도가 429를 일으키나요?

상대해야 할 숫자를 알아 두세요. BroadNet Inference 기준:

키 종류 분당 요청 동시 요청 기타
종량제 30 4 공유 지출 예산
시간제 키 120 스트림 1개 분당 토큰 300,000개
무제한 플랜 세션 — 세션당 요청 1개 토큰 계량 없음

LLM에서 가장 중요한 것은 동시 요청 수입니다. 스트리밍 답변은 마지막 토큰이 도착할 때까지 슬롯을 차지하므로, 긴 답변은 모델이 그 답변을 다 쓰는 동안 슬롯을 계속 붙잡고 있습니다(BroadNet이 밝힌 일반적인 속도는 초당 약 100토큰입니다). 키의 슬롯 4개보다 많은 병렬 호출을 보내면, 그 1분 동안 보낸 요청이 몇 개 되지 않아도 초과분은 429를 받습니다. 이것은 동시 처리 문제이며, 백오프만으로는 잘 해결되지 않습니다. 출시 전에 한도에 맞춰 워커 수를 정하려면 무료 LLM 속도 제한 계산기를 사용하세요. 항목이 많은 고정된 작업이라면 LLM 배치 작업 플래너가 같은 한도를 실행 시간으로 바꿔 줍니다. 다른 제공업체는 한도를 다르게 셉니다(분당 토큰, 일일 요청, 동시 요청). 제공업체별 LLM API 속도 제한에서 13곳을 각사 문서 기준으로 비교합니다.

지터를 둔 백오프는 어떻게 작성하나요?

일반적인 지수 백오프는 1, 2, 4, 8초를 기다립니다. 워커 100개가 같은 순간에 제한을 받았다면 모두 같은 순간에 돌아옵니다. AWS가 경쟁하는 클라이언트 100개로 시뮬레이션한 결과, 전체 지터는 지터 없는 백오프보다 호출 수를 절반 넘게 줄이고 더 빨리 끝났습니다. 가장 단순한 방식인 전체 지터(full jitter)는 0부터 지수 상한 사이에서 무작위로 기다립니다.

import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except (RateLimitError, APIStatusError, APIConnectionError) as e:
            status = getattr(e, "status_code", None)
            if status is not None and status not in RETRYABLE:
                raise  # 400, 401, 403...: retrying will not help
            if attempt == max_attempts - 1:
                raise
            retry_after = None
            if getattr(e, "response", None) is not None:
                retry_after = e.response.headers.get("retry-after")
            wait = random.uniform(0, min(cap, base * 2 ** attempt))
            if retry_after and retry_after.isdigit():
                wait = max(wait, float(retry_after))
            time.sleep(wait)

max_retries=0은 SDK 자체 재시도를 꺼서 이중으로 재시도하지 않게 합니다. SDK의 기본 동작으로 충분하다면 반대로 해도 됩니다. 직접 만든 루프를 빼고, Python SDK 가이드처럼 클라이언트에 max_retries=4를 설정하세요. 공식 Python과 Node SDK는 연결 오류, 408, 409, 429, 5xx를 기본적으로 두 번 재시도합니다.

Retry-After는 표준 헤더(RFC 9110)로, 초 단위 값이나 날짜를 담을 수 있습니다. BroadNet 문서는 이 헤더를 보장하지 않으므로, 코드에서는 선택 사항으로 다룹니다.

429가 나기 전에 막으려면 어떻게 하나요?

동시 요청 수를 키의 한도로 제한하세요. Python에서는 asyncio.Semaphore 객체 하나와 async with 블록 하나면 됩니다. 아래 코드는 예시로 4를 쓰니, 키의 동시 요청 한도(BroadNet 종량제 키는 4)로 바꿔 설정하세요.

import asyncio, os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4)  # match the key's in-flight limit

async def ask(prompt):
    async with slots:
        r = await client.chat.completions.create(
            model="broadnet/gemma-4-26b-a4b",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main(prompts):
    return await asyncio.gather(*(ask(p) for p in prompts))

results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))

gather는 모든 작업을 시작하지만, 동시에 실행되는 것은 세마포어가 허용하는 수만큼입니다. 나머지는 세마포어의 대기열에서 기다립니다. Node에서는 p-limit 패키지가 같은 역할을 하며, 여기서도 예시 값은 4입니다.

// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit

async function ask(prompt) {
  const r = await client.chat.completions.create({
    model: "broadnet/gemma-4-26b-a4b",
    messages: [{ role: "user", content: prompt }],
  });
  return r.choices[0].message.content;
}

const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));

분당 상한도 지키려면 60 / rpm초마다 허가를 하나씩 내주는 토큰 버킷을 추가하세요. 여기서 rpm은 키의 분당 요청 한도입니다(BroadNet 종량제 키는 30).

진짜 큐는 언제 필요한가요?

세마포어는 프로세스 하나 안에서만 동작합니다. 여러 워커나 서버가 키 하나를 공유하면 한도도 공유되는데, 각 프로세스는 자기 트래픽만 봅니다. 이때는 다음과 같이 하세요.

  1. 작업을 공유 큐(Redis, SQS, 데이터베이스 테이블)에 넣습니다.
  2. 키의 동시 요청 한도와 같은 수의 컨슈머를 고정해서 실행합니다.
  3. 작업마다 ID를 부여하고 결과를 ID별로 저장해, 재시도한 작업이 두 번 실행되지 않게 합니다.
  4. 대화형 트래픽과 배치 트래픽은 별도의 키나 별도의 큐로 보내, 밀린 배치 작업 때문에 답변을 기다리는 사용자가 막히지 않게 합니다.

Batch API 없이 항목 수천 개를 처리하는 대량 작업은 재개 가능한 배치 실행기를 참고하세요.

어떤 재시도 실수가 429를 장애로 키우나요?

  • 상한 없는 재시도. 장애가 길어지는 동안 상한 없는 재시도 루프는 부하를, 그리고 토큰당 과금에서는 청구액을 몇 배로 불립니다.
  • 절반쯤 끝난 스트림을 무작정 재시도하기. 스트림이 이미 토큰을 반환했다면 재시도는 새로운 추론이며, 사용자는 같은 텍스트를 두 번 볼 수 있습니다. 끊긴 스트림을 감지하는 방법은 스트리밍 글을 참고하세요.
  • 계정 오류 재시도. 종량제 허용량을 모두 쓴 401이나 잔액 부족으로 인한 402는 저절로 해결되지 않습니다.

모든 재시도를 상태, 대기 시간, X-Request-ID 응답 헤더와 함께 기록하세요. BroadNet 문서는 지원 요청을 위해 이 헤더를 보관하라고 안내합니다. 재시도 비율이 오르는 것은 용량이 더 필요하다는 가장 이른 경고입니다. 기록 방법은 사용량 로깅에 있습니다.

BroadNet Inference는 어디에 적합한가요?

BroadNet의 한도는 공개되어 있고, 설계에 반영하기 좋을 만큼 작습니다. 종량제 키의 동시 요청은 4개입니다. 앱과 에이전트에는 맞지만, 키 하나로 병렬 호출 수백 개를 원하는 대량 작업에는 너무 빠듯합니다. 에이전트라면 무제한 플랜에는 토큰 계량이 없고 세션당 한 번에 요청 1개를 처리합니다. 병렬 작업에는 병렬 코딩 에이전트 실행하기에서 설명하듯 세션을 추가하면 됩니다. 현재 한도는 API 레퍼런스에 있습니다.

자주 묻는 질문

LLM API에서 HTTP 429는 무슨 뜻인가요?

Too Many Requests입니다. 분당 요청 수, 동시 요청 수, 분당 토큰 수, 지출 중 하나의 한도를 넘었다는 뜻입니다. 요청은 처리되지 않았으므로 잠시 기다린 뒤 다시 보내도 안전합니다.

429 오류 후 재시도까지 얼마나 기다려야 하나요?

서버가 Retry-After를 보내면 그 값을 따르세요. 그렇지 않으면 1초 정도에서 시작해 시도마다 두 배로 늘리고, 상한을 30~60초 정도로 둔 뒤, 0부터 그 상한 사이에서 무작위로 대기 시간을 고르세요. 4~6회 시도 후에는 멈추세요.

LLM API의 500, 503 오류도 재시도해야 하나요?

네, 같은 방식으로 상한을 둔 백오프를 적용하세요. 서버 쪽 문제이기 때문입니다. 400, 401, 403, 422는 매번 똑같이 실패하므로 요청을 고치세요.

OpenAI SDK는 429를 자동으로 재시도하나요?

네. 공식 Python과 Node SDK는 연결 오류, 408, 409, 429, 5xx를 기본적으로 짧은 지수 백오프로 두 번 재시도합니다. 배치 작업에서는 max_retries를 올리고, 동시 처리 제한은 직접 추가하세요.

분당 요청 한도보다 적게 보냈는데 왜 429가 나나요?

대개 동시 처리 한도 때문입니다. 긴 스트리밍 응답은 몇십 초 동안 처리 중 상태로 남으므로, 분당 요청 수는 적어 보여도 병렬 호출 몇 개만으로 동시 요청 상한에 걸릴 수 있습니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기