# 에러

> 에러 응답 형식과 주요 HTTP 상태 코드를 설명합니다.

Source: https://kiln.bricksum.com/docs/ko/errors

에러는 표준 HTTP 상태 코드와 함께 반환됩니다. 본문 형식은 요청을 거부한 계층에 따라 다르므로 message 문구가 아니라 HTTP 상태와 error.code로 분기하세요. API가 반환하는 본문 형식은 아래에 예시와 함께 정리했습니다.

참고

분기는 상태 코드와 error.code로만 하고 message로는 하지 마세요. message는 사람이 읽는 문구라 표현이 바뀔 수 있고, 계약에 해당하는 값은 상태 코드와 code입니다.

## HTTP 상태

API가 반환하는 상태를 대응 방법별로 묶으면 다음과 같습니다.

- 400, 404, 405: 요청 자체가 잘못되었습니다. 고친 뒤 다시 보내세요.
- 401, 403: API 키를 쓸 수 없습니다. 키를 확인하거나 새로 발급하세요.
- 402: 크레딧 잔액, 조직 예산, 키 지출 한도 중 하나가 소진되었습니다.
- 429: 레이트 리밋을 초과했습니다. 리셋 이후에 재시도하거나 백오프하세요.
- 500, 502, 503: Kiln 쪽 문제입니다. 지수 백오프로 재시도하세요.

## 상태 코드

이 표가 상태 코드의 기준이며 다른 페이지는 이 표로 연결합니다. 클라이언트에서 아래 코드를 명시적으로 처리하세요.

| 상태 | error.code | 원인 | 대응 |
| --- | --- | --- | --- |
| 400 | empty_array, unsupported_parameter | 잘못된 요청입니다. 형식이 틀린 JSON, 유효하지 않은 파라미터, 모델 페이지에 나오는 모델별 컨텍스트 길이 초과, /v1/chat/completions의 비어 있거나 누락된 messages 배열, gpt-oss 모델의 ignore_eos, /v1/responses의 previous_response_id가 해당합니다. | 요청 페이로드를 수정하세요. 그대로 재시도하지 마세요. |
| 401 | - | 인증 실패입니다. API 키가 없거나, 형식이 틀렸거나, 등록되지 않았거나, 만료되었습니다. | Authorization 또는 x-api-key 헤더, 키 값, 키 만료일을 확인하세요. |
| 402 | - | 결제가 필요합니다. 크레딧 잔액이 소진되었거나, 조직이 월 예산에 도달했거나, 키가 지출 한도에 도달했습니다. | 크레딧을 충전하거나 관리자에게 예산 또는 키 지출 한도 상향을 요청하세요. 그 전에는 재시도하지 마세요. |
| 403 | - | 권한이 없습니다. API 키가 일시중지되었거나 폐기되었습니다. 보관된 프로젝트의 키는 일시중지로 처리합니다. | 콘솔에서 키를 재활성화하고, 폐기된 키라면 새 키를 발급하세요. |
| 404 | model_not_found, unknown_url, not_found | 찾을 수 없습니다. 모델이 없거나 사용 권한이 없는 경우(model_not_found), 제공하지 않는 경로인 경우(unknown_url), 저장된 응답을 조회한 경우(not_found, 응답은 보관하지 않습니다)입니다. | 모델 ID는 GET /v1/models 응답과, 경로는 API 레퍼런스와 대조하세요. |
| 405 | method_not_allowed | 허용되지 않는 메서드입니다. 제공하는 경로이지만 이 HTTP 메서드는 받지 않습니다. | 응답의 Allow 헤더에 적힌 메서드를 사용하세요. |
| 429 | rate_limit_exceeded (동시성만) | 요청이 너무 많습니다. 조직 단위 한도를 초과했습니다. 기본 60 요청/분, 설정된 경우 분당 토큰 한도, 또는 동시 8 요청입니다. | 분당 요청 또는 분당 토큰 429에는 x-ratelimit-reset이 실리므로 그 초만큼 기다리세요. 동시성 429에는 레이트 리밋 헤더가 없으므로 지수 백오프를 사용하세요. |
| 502 | - | 게이트웨이 에러입니다. 업스트림 모델 백엔드가 실패했거나 백엔드에 도달할 수 없습니다. | 지수 백오프로 재시도하고, 긴 생성에는 스트리밍을 사용하세요. 지속되면 지원팀에 문의하세요. |
| 503 | - | 서비스를 이용할 수 없습니다. 정비 모드이거나 사용 가능한 모델 백엔드가 없습니다. | 정비 중에는 응답에 Retry-After 헤더(HTTP 날짜)가 실리므로 그때까지 기다리세요. 그 외에는 지수 백오프로 재시도하세요. |
| 5xx | - | 서버 에러입니다. Kiln 쪽의 일시적인 문제입니다. | 지수 백오프로 재시도하세요. 지속되면 지원팀에 문의하세요. |

## 에러 본문 형식

- 인증, 크레딧, RPM/TPM 한도 거부(401, 402, 403, 429): {"error":{"message","type":"authorization"}} 형식입니다. code와 param 필드는 없습니다.
- 요청 검증과 동시성 한도 거부: error.type은 invalid_request_error이고 param과 code가 추가됩니다. code는 model_not_found, empty_array, unsupported_parameter, rate_limit_exceeded, unknown_url, method_not_allowed, not_found 중 하나입니다.
- /v1/messages에서 인증 이후에 반환되는 에러는 Anthropic 형식 {"type":"error","error":{"type","message"}}을 사용합니다.
- GET /v1/key는 {"error":{"message","code"}} 형식을 반환하며 type 필드는 없습니다. 키가 없거나, 등록되지 않았거나, 일시중지·만료된 경우 code는 unauthorized입니다.
- OpenAI 형식 엔드포인트의 502와, 사용 가능한 모델 백엔드가 없어 발생한 503은 본문이 일반 텍스트이므로 JSON으로 파싱하지 마세요. 정비 중 503은 type이 "maintenance"인 JSON입니다.

**게이트웨이 거부**
```json
{
  "error": {
    "message": "missing or malformed API key",
    "type": "authorization"
  }
}
```

**요청 검증**
```json
{
  "error": {
    "message": "The model does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

**Anthropic 형식(/v1/messages)**
```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required"
  }
}
```

**GET /v1/key**
```json
{
  "error": {
    "message": "invalid API key",
    "code": "unauthorized"
  }
}
```

**일반 텍스트(502, 503)**
```http
HTTP/1.1 502 Bad Gateway
Content-Type: text/plain; charset=utf-8

upstream error
```

## 스트림 시작 전과 스트림 도중의 실패

### 바이트가 나가기 전

거부된 요청은 응답 바이트가 하나도 나가기 전에 실패합니다. 클라이언트는 2xx가 아닌 상태와 위 본문 중 하나를 받고, 토큰은 생성되지 않으며, 과금도 되지 않습니다. 위 표의 모든 행이 이 경우에 해당합니다.

### 200 이후

게이트웨이가 200과 첫 스트림 바이트를 내보낸 뒤에는 HTTP 상태를 바꿀 수 없습니다. 모델 서버가 생성 도중에 실패하면 스트림이 일찍 끊깁니다. 마지막 청크와 data: [DONE] 표시 없이 종료되거나, 스트림 안에 error 객체가 실려 옵니다. 이렇게 실패한 생성은 과금하지 않습니다.

끊긴 스트림은 짧은 답변처럼 보이므로 다음을 확인하세요.

- data: [DONE] 없이 끝난 스트림은 상태가 200이었더라도 실패로 처리하세요.
- 마지막 청크에 finish_reason이 있는지 확인하세요. finish_reason 없이 끝난 스트림은 완료된 것이 아닙니다.
- stream_options.include_usage를 true로 설정하고, usage 청크가 없으면 실패로 처리하세요.
- 응답의 X-Neocloud-Generation-Id 헤더를 로그에 남겨 실패한 요청을 나중에 추적하세요.

429 처리와 재시도 전략은 [레이트 리밋](https://kiln.bricksum.com/docs/ko/rate-limits) 페이지를 참고하세요.