> ## Documentation Index
> Fetch the complete documentation index at: https://docs.k-router.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 에러 코드

> K-Router API 에러 코드 레퍼런스

# 에러 코드

K-Router API는 표준 HTTP 상태 코드와 함께 구조화된 에러 응답을 반환합니다.

## 에러 응답 형식

```json theme={null}
{
  "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` | 잔액 부족. 대시보드에서 결제하여 사용 한도를 충전하세요. |

### 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

서버 내부 오류입니다. 지속될 경우 [contact@k-router.com](mailto:contact@k-router.com)으로 문의하세요.

| 코드               | 설명             |
| ---------------- | -------------- |
| `server_error`   | 내부 처리 오류       |
| `upstream_error` | 업스트림 AI 제공자 오류 |

## 에러 처리 예시

```python theme={null}
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}")
```

<Tip>
  429 에러 발생 시 지수 백오프(exponential backoff)를 적용하여 재시도하는 것을 권장합니다.
</Tip>