> ## Documentation Index
> Fetch the complete documentation index at: https://dev-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`로 잔액 확인 후 충전                             |
| `404` | 리소스 없음                                           | ID가 내 조직의 리소스인지 확인                                        |
| `409` | 상태 충돌 (예: 세트당 프롬프트 1,000개 초과)                    | 리소스 상태를 확인한 뒤 요청 조정                                       |
| `413` | 요청 본문이 2MiB 초과 (`COMMON_REQUEST_BODY_TOO_LARGE`) | 요청을 나눠 보내기                                                |
| `429` | 요청 한도 초과                                         | `Retry-After` 헤더만큼 대기 후 재시도. [Rate Limit](/rate-limit) 참고 |
| `5xx` | 서버 오류 또는 외부 공급자 장애                               | 지수 백오프로 재시도                                               |

## 주요 에러 코드

| 코드                                 | HTTP | 설명                              |
| ---------------------------------- | ---- | ------------------------------- |
| `COMMON_VALIDATION`                | 400  | 필드 검증 실패. `details`에 위반 목록      |
| `COMMON_INVALID_CURSOR`            | 400  | cursor 형식 오류. 첫 페이지부터 다시 조회     |
| `COMMON_UNAUTHORIZED`              | 401  | 인증 실패                           |
| `RUN_PROMPT_TARGET_REQUIRED`       | 400  | `promptIDs`·`promptSetID` 지정 오류 |
| `RUN_TOO_MANY_TASKS`               | 400  | 실행 요청 하나의 총 실행 수 10,000개 초과     |
| `PROMPT_SET_NOT_FOUND`             | 404  | 프롬프트 세트 없음                      |
| `PROMPT_SET_EMPTY`                 | 400  | 빈 세트로 실행 요청                     |
| `PROMPT_SET_PROMPT_LIMIT_EXCEEDED` | 409  | 세트당 프롬프트 1,000개 초과              |
| `QUESTION_NOT_FOUND`               | 404  | 프롬프트 없음 (조회·수정·삭제 시)            |
| `PROMPT_NOT_FOUND`                 | 404  | 실행 요청의 `promptIDs`에 없는 프롬프트 포함  |
| `ANSWER_NOT_FOUND`                 | 404  | 답변 없음                           |
| `USER_BRAND_NOT_FOUND`             | 404  | 브랜드 없음                          |
| `MODEL_NOT_SUPPORTED`              | 400  | 지원하지 않는 모델                      |
| `REGION_NOT_SUPPORTED_FOR_MODEL`   | 400  | 모델이 지원하지 않는 지역                  |
| `INSUFFICIENT_CREDITS`             | 402  | 크레딧 부족                          |
| `PLATFORM_RATE_LIMIT_EXCEEDED`     | 429  | 요청 한도 초과                        |

<Info>
  프롬프트 관련 에러는 `QUESTION_`, 브랜드 관련 에러는 `USER_BRAND_` 접두사를 사용합니다. 각각 프롬프트·브랜드 리소스를 가리킵니다.
</Info>

## 재시도 전략

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