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

# 에러 처리

> Tiro API의 에러를 처리하는 전체 가이드

## 에러 응답 형식

모든 Tiro API 에러는 일관된 JSON 구조를 따라요.

```json theme={"system"}
{
  "error": {
    "code": 400001,
    "errorType": "bad_request",
    "message": "Human readable error message",
    "detail": "Additional context or null"
  }
}
```

### 필드

| 필드          | 타입                       | 설명                                                                                      |
| ----------- | ------------------------ | --------------------------------------------------------------------------------------- |
| `code`      | integer                  | `AAABBB` 형태의 6자리 에러 코드예요. 앞 3자리는 HTTP 상태와 일치하고, 뒤 3자리는 상태별 일련번호예요. 세밀한 클라이언트 분기에 사용하세요. |
| `errorType` | string                   | HTTP 상태에서 파생된 큰 범주의 분류예요. 시간이 지나도 안정적이라 클라이언트 분기에 안전해요. 아래 표를 참고하세요.                    |
| `message`   | string                   | 사람이 읽을 수 있는 에러 메시지예요. 안정적이지 않으니 분기에 사용하지 마세요.                                           |
| `detail`    | object \| string \| null | 선택적인 추가 정보예요 (에러마다 달라요).                                                                |

## HTTP 상태 코드 & 에러 타입

| 상태      | `errorType`            | 의미                                  |
| ------- | ---------------------- | ----------------------------------- |
| **400** | `bad_request`          | 잘못된 요청 형식 또는 파라미터                   |
| **401** | `unauthorized`         | API 키 누락 또는 무효                      |
| **403** | `forbidden`            | API 키에 필요한 권한 없음                    |
| **404** | `not_found`            | 리소스가 존재하지 않음                        |
| **406** | `not_acceptable`       | 지원하지 않는 `Accept` 헤더                 |
| **409** | `conflict`             | 리소스가 이미 존재하거나 상태 충돌                 |
| **413** | `payload_too_large`    | 요청 본문이 크기 제한 초과                     |
| **422** | `unprocessable_entity` | 형식은 유효하지만 데이터가 유효하지 않음              |
| **429** | `too_many_requests`    | rate limit 초과                       |
| **5xx** | `internal_error`       | 서버 측 에러 (더 파싱하지 말고 backoff로 재시도하세요) |