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 가이드에 나와 있습니다.
