에러 코드
K-Router API는 표준 HTTP 상태 코드와 함께 구조화된 에러 응답을 반환합니다.
에러 응답 형식
{
"error": {
"message": "에러 설명",
"type": "에러 유형",
"code": "에러 코드"
}
}
상태 코드
400 — Bad Request
잘못된 요청입니다.
| 코드 | 설명 |
|---|
model_not_found | 지원하지 않는 모델 ID |
messages_too_long | 메시지 수 100개 초과 |
content_too_long | 단일 메시지 100,000자 초과 |
401 — Unauthorized
인증 실패입니다.
| 코드 | 설명 |
|---|
missing_api_key | Authorization 헤더 누락 |
invalid_api_key | 유효하지 않거나 비활성화된 API 키 |
402 — Payment Required
크레딧이 부족합니다.
| 코드 | 설명 |
|---|
insufficient_credits | 잔액 부족. 대시보드에서 충전 필요 |
insufficient_credit | 잔액 0 이하 |
403 — Forbidden
콘텐츠 정책 위반입니다.
| 코드 | 설명 |
|---|
moderation_blocked | 콘텐츠 검토에서 차단됨 |
429 — Too Many Requests
요청 제한 초과입니다.
| 코드 | 설명 |
|---|
rate_limit_exceeded | 분당 요청 한도 초과 (기본 300/분) |
daily_limit_exceeded | 일일 요청 한도 초과 (기본 50,000/일) |
ip_blocked | 인증 실패 반복으로 IP 차단 (5분) |
500 — Internal Server Error
서버 내부 오류입니다. 지속될 경우 고객센터에 문의하세요.
| 코드 | 설명 |
|---|
server_error | 내부 처리 오류 |
upstream_error | 업스트림 AI 제공자 오류 |
에러 처리 예시
from openai import OpenAI, APIError
client = OpenAI(
api_key="kr-your-api-key",
base_url="https://api.k-router.com/v1"
)
try:
response = client.chat.completions.create(
model="kr/gpt54",
messages=[{"role": "user", "content": "안녕하세요"}]
)
except APIError as e:
if e.status_code == 402:
print("크레딧을 충전하세요!")
elif e.status_code == 429:
print("요청 제한 초과. 잠시 후 재시도하세요.")
else:
print(f"에러: {e.message}")
429 에러 발생 시 지수 백오프(exponential backoff)를 적용하여 재시도하는 것을 권장합니다.
