BroadRouter
시작하기

BroadNet Inference 오류 코드와 재시도해야 하는 경우

업데이트

재시도 여부는 본문을 파싱하기 전에 HTTP 상태 코드로 판단하세요. 429와 5xx는 횟수와 대기 시간에 상한을 둔 지수 백오프로 재시도합니다. 400, 403, 413, 422는 요청을 고친 뒤에 다시 보내세요. 401이면 키와 잔액을, 402면 계정 충전을 확인하세요. 지원 요청에 대비해 X-Request-ID 헤더는 항상 로그에 남기세요.

API는 일반적인 HTTP 상태 코드와 기계 판독용 오류 코드를 반환합니다. 다음에 할 일은 상태 코드를 보고 정하세요. 아래 표는 BroadNet의 API 레퍼런스를 따릅니다.

상태 코드 의미 조치
400 / 422 잘못된 요청 또는 필드 먼저 요청을 고치세요
401 키 누락, 유효하지 않거나 만료된 키, 차단된 종량제 예산 또는 소진된 사용 가능 금액 키 상태와 계정 잔액을 확인하세요
402 insufficient_balance 계정 잔액으로 구매 금액을 충당할 수 없음. 본문에 잔액과 가격이 포함됨 계정을 충전한 뒤 다시 시도하세요
403 모델, 경로 또는 IP 정책에 의해 거부됨 불일치를 해결하세요. 예: IP 허용 목록
409 계정 상태와 충돌: mint_in_progress, key_limit_reached, credential_limit_reached, key_pending mint_in_progress만 같은 request_id로 재시도하세요
413 요청이 너무 큼. 전사 파일은 최대 26,214,400바이트 요청 크기를 줄이세요
429 요청 속도, 동시 실행 수, 토큰 속도 또는 지출 한도 도달 응답 상세 내용을 읽고 기다렸다가 재시도하세요
500 / 502 / 503 / 504 서버 측 처리 문제 상한을 둔 지수 백오프로 재시도하세요. 시간제 키 구매에는 같은 request_id를 재사용하세요

BroadNet 문서는 JSON 본문을 파싱하기 전에 HTTP 상태 코드를 먼저 확인하고, 기계 판독용 error 코드가 있으면 그다음에 읽으라고 안내합니다.

어떤 한도 때문에 429가 발생하나요?

종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. BroadNet 문서에 따르면 시간제 키는 분당 120 요청, 스트림 1개, 분당 300,000 토큰까지 허용합니다. 무제한 플랜에서는 세션마다 한 번에 요청 하나를 처리합니다. 이 한도를 OpenAI, Anthropic, Groq, DeepSeek과 비교하려면 제공업체별 LLM API 속도 제한을 읽어 보세요.

OpenAI SDK로 재시도하려면 어떻게 하나요?

GitHub의 README에 따르면 OpenAI Python SDK는 이미 연결 오류와 408, 409, 429, 5xx 응답을 기본적으로 짧은 지수 백오프로 두 번 재시도합니다. 기본 타임아웃은 10분입니다. 두 값을 명시적으로 설정하세요. 아래 예에서 max_retries를 0으로 두면 자동 재시도가 꺼지고, timeout은 초 단위이므로 추론이 긴 답변에서는 늘리세요.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
    max_retries=4,   # 0 turns automatic retries off
    timeout=120,     # seconds; raise it for long reasoning answers
)

백오프를 직접 구현하려면 어떻게 하나요?

SDK 없이 API를 호출한다면 시도 횟수와 대기 시간 모두에 상한을 두세요. 아래 함수는 재시도 대상이 아닌 상태 코드(성공했거나, 재시도가 아니라 수정이 필요한 오류)를 받으면 바로 반환합니다.

import random, time, requests

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

def post_with_backoff(url, headers, body, tries=5):
    for attempt in range(tries):
        r = requests.post(url, headers=headers, json=body, timeout=120)
        if r.status_code not in RETRY:
            return r                      # success, or an error to fix rather than retry
        time.sleep(min(30, 2 ** attempt) + random.random())
    return r

400, 403, 413, 422는 그대로 재시도하지 마세요. 같은 요청은 같은 이유로 실패합니다. 채팅 요청을 재시도할 때마다 새로운 추론이 실행되며, 종량제에서는 다시 과금됩니다. 일반적인 패턴은 지수 백오프를 참고하세요.

시간제 키 구매를 안전하게 재시도하기

POST /portal/keys/hourly는 request_id를 받습니다. 타임아웃, 연결 끊김, 409 mint_in_progress, 5xx가 발생한 뒤에는 같은 request_id로 재시도하세요. 재사용한 request_id로는 두 번째 키가 생성되거나 과금되지 않으며, 재요청에는 already_issued: true와 별칭이 반환됩니다. 첫 번째 결과를 확인하기 전에는 새 ID를 만들지 마세요. 자세한 내용은 멱등성 키를 참고하세요.

문제 해결

  • 충전 직후 401. BroadNet 계정 페이지는 마지막으로 기록된 사용 가능 금액을 보여 주며, 충전 내역이 반영되는 동안에는 업데이트 중으로 표시합니다. 페이지를 새로고침하고 반영이 끝난 뒤 다시 시도하세요.
  • 분당 요청이 몇 개뿐인데 429. 긴 스트림을 병렬로 실행하는 경우처럼, 동시 처리 한도(4 건)에 걸렸을 가능성이 큽니다. 작은 워커 풀을 쓰세요.
  • 한 모델에서만 403. 키의 정책이 해당 모델이나 경로를 포함하지 않습니다. 예를 들어 플랜 키는 broadnet/deepseek-v4.1-flash 모델용이고, 시간제 키는 broadnet/gemma-4-26b-a4b 모델에만 적용됩니다.
  • SDK가 재시도해서 두 번 과금됨. 재시도한 채팅 요청은 새로운 추론입니다. 중복 답변이 실패보다 비용이 큰 곳에서는 max_retries=0으로 설정하세요.

지원팀에 보낼 정보

X-Request-ID 헤더 값, UTC 타임스탬프, 경로, HTTP 상태 코드, 키 별칭을 함께 보내세요. 키 자체는 절대 보내지 마세요. 헤더를 읽는 방법은 OpenAI Python SDK 가이드에 나와 있습니다.

자주 묻는 질문

LLM API에서 429 오류가 나면 재시도해야 하나요?

네. 상한을 둔 지수 백오프로 재시도하세요. BroadNet Inference의 429는 요청 속도, 동시 실행 수, 토큰 속도 또는 지출 한도에 도달했다는 뜻입니다. 계속 발생하면 병렬 처리 수를 줄이고, 원인이 지출 한도라면 재시도를 멈추세요.

키가 맞는데 401이 나오는 이유는 무엇인가요?

BroadNet에서 401은 키가 틀렸거나 만료된 경우뿐 아니라, 종량제 사용 가능 금액이 소진되었거나 예산이 차단된 경우도 포함합니다. 계정 페이지에서 계정 잔액과 키 상태를 확인하세요.

여기서 401과 403은 어떻게 다른가요?

401은 키나 계정의 사용 가능 금액 문제입니다. 403은 키는 유효하지만 모델, 경로 또는 IP 정책이 요청을 거부했다는 뜻입니다. 예를 들어 허용 목록에 없는 주소에서 호출한 경우입니다.

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

네. OpenAI Python SDK는 기본적으로 연결 오류, 408, 409, 429, 5xx를 짧은 지수 백오프로 두 번 재시도합니다. 횟수를 바꾸려면 max_retries를 설정하고, 재시도를 끄려면 0으로 지정하세요.

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