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

# 오류 처리

> 오류 응답 형식, 주요 오류 코드, 재시도 전략

모든 오류는 같은 형식으로 반환됩니다. `code`로 분기하고, `message`는 사람이 읽는 용도로만 사용하세요.

```json theme={null}
{
  "code": "PROMPT_SET_NOT_FOUND",
  "message": "프롬프트 세트를 찾을 수 없습니다"
}
```

검증 오류는 `details`에 필드별 위반 내용이 배열로 포함됩니다.

```json theme={null}
{
  "code": "COMMON_VALIDATION",
  "message": "데이터 검증에 실패했습니다",
  "details": [
    "models: 최소 1개 이상이어야 합니다",
    "keywords: 최대 100개까지 입력할 수 있습니다"
  ]
}
```

<Note>
  오류 메시지는 `Accept-Language` 헤더에 따라 한국어(`ko`) 또는 영어(`en`)로
  반환됩니다. 헤더가 없거나 지원하지 않는 언어면 영어로 반환됩니다. `code` 값은
  언어와 무관하게 항상 같습니다.
</Note>

## HTTP 상태 코드

| 상태    | 의미                                               | 대응                                                               |
| ----- | ------------------------------------------------ | ---------------------------------------------------------------- |
| `400` | 잘못된 요청 (검증 실패, 잘못된 cursor 등)                     | 요청을 수정한 뒤 재시도. 같은 요청의 재시도는 무의미합니다                                |
| `401` | 인증 실패                                            | `API-Key` 헤더와 키 값 확인                                             |
| `402` | 크레딧 부족 (`INSUFFICIENT_CREDITS`)                  | `GET /credits/me`로 잔액 확인 후 충전. [크레딧](/guides/credits) 참고         |
| `404` | 리소스 없음                                           | ID가 내 조직의 리소스인지 확인                                               |
| `409` | 상태 충돌 (예: 세트당 프롬프트 1,000개 초과)                    | 리소스 상태를 확인한 뒤 요청 조정                                              |
| `413` | 요청 본문이 2MiB 초과 (`COMMON_REQUEST_BODY_TOO_LARGE`) | 요청을 나눠 보내기                                                       |
| `429` | 요청 한도 초과                                         | `Retry-After` 헤더만큼 대기 후 재시도. [Rate Limit](/guides/rate-limit) 참고 |
| `5xx` | 서버 오류 또는 외부 공급자 장애                               | 지수 백오프로 재시도                                                      |

## 공통 오류 코드

엔드포인트를 가리지 않고 발생하는 코드입니다. 이 코드들의 처리 로직은 한 번 만들어 두고 모든 호출에 재사용하세요.

| 코드                              | HTTP | 설명                                                    |
| ------------------------------- | ---- | ----------------------------------------------------- |
| `COMMON_BINDING`                | 400  | 요청 본문을 해석할 수 없음 (JSON 형식 오류 등)                        |
| `COMMON_VALIDATION`             | 400  | 필드 검증 실패. `details`에 위반 목록                            |
| `COMMON_INVALID_CURSOR`         | 400  | cursor 형식 오류. 첫 페이지부터 다시 조회                           |
| `PLATFORM_INVALID_ID`           | 400  | 리소스 ID 형식 오류. 없는 리소스가 아니라 형식 문제이므로 `404`가 아닌 `400`입니다 |
| `COMMON_UNAUTHORIZED`           | 401  | 인증 실패                                                 |
| `INSUFFICIENT_CREDITS`          | 402  | 크레딧 부족                                                |
| `COMMON_REQUEST_BODY_TOO_LARGE` | 413  | 요청 본문 2MiB 초과                                         |
| `PLATFORM_RATE_LIMIT_EXCEEDED`  | 429  | 요청 한도 초과                                              |

## 엔드포인트별 오류

`PROMPT_SET_NOT_FOUND`, `RUN_TOO_MANY_TASKS`처럼 특정 리소스에서만 나는 코드는 여기서 다루지 않습니다. 각 [API Reference](/api-reference/overview) 페이지 상단의 **오류** 표에 해당 엔드포인트에서 실제로 발생하는 코드만 정리돼 있습니다. 이 표는 API 스펙에서 자동 생성되므로 서버와 항상 일치합니다.

<Info>
  코드 접두사가 리소스를 가리킵니다. 프롬프트는 `QUESTION_`, 브랜드는
  `USER_BRAND_`, 프롬프트 세트는 `PROMPT_SET_`, 실행 요청은 `RUN_` 입니다.
</Info>

## 재시도 전략

* `429` — `Retry-After` 헤더의 초만큼 대기 후 재시도합니다.
* `502` / `503` — 외부 공급자 장애일 수 있습니다. 지수 백오프(예: 1초 → 2초 → 4초)로 재시도합니다.
* `400` / `404` — 재시도해도 결과가 같습니다. 요청을 수정하세요.
* 폴링 중 일시적 오류가 나도 실행 수집 자체는 백그라운드에서 계속 진행됩니다. 다음 폴링에서 이어서 확인하면 됩니다.