# API 오류 처리 — 오류 유형, 코드 및 doc_url

> 모든 v1 오류는 type, code, message, doc_url을 포함하는 JSON 객체입니다. 이 페이지는 전체 오류 유형 분류와 모든 개별 오류 코드를 문서화하며, 반환된 doc_url이 연결되는 대상입니다.

실패한 모든 v1 요청은 아래에 전체 목록이 나와 있는 동일한 JSON 형태를 반환합니다. 이 페이지는 또한 모든 오류의 `doc_url`이 연결되는 대상입니다. 각 코드에는 고유한 앵커 섹션이 있으므로, 실제 오류 응답에서 `doc_url`을 따라가면 해당 코드에 대한 설명으로 바로 이동합니다.

## 오류 형태

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "필수 매개변수가 누락되었습니다.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter",
    "param": "file"
  }
}
```

- `type` — 이 오류가 속하는 광범위한 범주입니다. 모든 개별 `code`를 확인하지 않고 오류 처리 코드에서 대략적인 분기를 수행하는 데 유용합니다.
- `code` — 구체적이고 안정적인 오류 식별자입니다. 코드에서 일치시켜야 하는 값이며, 나중에 `message` 문구가 개선되어도 변경되지 않습니다.
- `message` — 사람이 읽을 수 있는 설명입니다. 로그 및 디버깅에 유용하며, 구문 분석용이 아닙니다.
- `doc_url` — 해당 `code`에 대한 이 페이지 섹션의 직접 링크입니다.
- `param` — 유효성 검사 스타일 오류(`missing_parameter`, `invalid_parameter`, `duplicate_field_name`)에만 존재하며, 오류를 발생시킨 특정 요청 필드를 지정합니다. 해당되지 않는 경우 `null`이 아니라 완전히 생략됩니다.

## 오류 유형

모든 `code`는 정확히 하나의 `type`에 속합니다:

| 유형 | 의미 |
| --- | --- |
| authentication_error | 요청 인증 방식에 문제가 있습니다. |
| invalid_request_error | 요청 자체의 형식이 잘못되었습니다. 매개변수가 누락되었거나 유효하지 않습니다. |
| not_found_error | URL에서 참조한 리소스가 존재하지 않거나 계정에 속하지 않습니다. |
| insufficient_credits | 계정에 요청한 작업을 수행할 크레딧이 충분하지 않습니다. |
| rate_limit_error | 이 엔드포인트 카테고리의 요청 속도를 초과했습니다. 자세한 내용은 속도 제한 을 참조하세요. |
| internal_error | 저희 쪽에서 문제가 발생했습니다. 고객님 쪽 문제가 아닙니다. |

## 특수 사례: `processing_error`

`processing_error`는 최상위 `{"error": ...}` 응답에서 볼 수 있는 `type`이 **아닙니다**. 이 오류로 인해 API 호출 자체가 실패하지는 않습니다. 대신, 배치 내에서 추출할 수 없었던 개별 문서를 설명합니다. 성공한 동일 배치의 다른 문서들과 함께, 정상 200 OK 응답을 반환하는 `GET /batches/{batch_name}/results` 응답에서 해당 문서에 대해 `"status": "failed"`로 표시됩니다. 성공한 API 호출 내의 문서 수준 실패를 전체 배치를 재시도해야 하는 오류로 간주하지 마십시오. 각 문서의 개별 `status`를 확인하세요.

## 오류 코드

### missing_api_key

**유형:** `authentication_error` · **HTTP 상태:** 401

API 키가 제공되지 않았습니다. `Authorization: Bearer <key>` 형식으로 전송하세요.

### invalid_api_key

**유형:** `authentication_error` · **HTTP 상태:** 401

제공된 API 키가 유효하지 않거나, 해당 계정이 비활성화되었습니다.

### plan_required

**유형:** `authentication_error` · **HTTP 상태:** 403

Free 요금제에서는 API를 사용할 수 없습니다. Basic 이상으로 업그레이드하여 사용하세요.

### missing_parameter

**유형:** `invalid_request_error` · **HTTP 상태:** 400

필수 매개변수가 누락되었습니다. 오류 객체의 `param` 필드에서 어떤 매개변수인지 확인하세요.

### invalid_parameter

**유형:** `invalid_request_error` · **HTTP 상태:** 400

매개변수의 값이 유효하지 않습니다. 자세한 내용은 `param` 및 `message`를 확인하세요. 이 코드는 잘못된 `crop` 문자열부터 범위를 벗어난 `limit`, 처리할 항목이 없는 배치까지 모든 상황을 포괄합니다.

### duplicate_field_name

**유형:** `invalid_request_error` · **HTTP 상태:** 400

이 템플릿에 동일한 이름의 필드가 이미 존재합니다. 필드 이름은 템플릿 내에서 고유해야 합니다.

### idempotency_key_reused

**유형:** `invalid_request_error` · **HTTP 상태:** 400

이 `Idempotency-Key`는 다른 매개변수를 가진 요청에 이미 사용되었습니다. 완전히 다른 요청에는 새 키를 사용하세요. 자세한 동작은 [멱등성](/developers/guides/idempotency)을 참조하세요.

### document_not_found

**유형:** `not_found_error` · **HTTP 상태:** 404

지정된 ID의 문서를 찾을 수 없습니다.

### batch_not_found

**유형:** `not_found_error` · **HTTP 상태:** 404

지정된 이름의 배치를 찾을 수 없습니다.

### template_not_found

**유형:** `not_found_error` · **HTTP 상태:** 404

지정된 ID의 템플릿을 찾을 수 없습니다.

### insufficient_credits

**유형:** `insufficient_credits` · **HTTP 상태:** 402

이 작업을 수행하기에 크레딧이 부족합니다. 재시도하기 전에 `GET /account`에서 현재 `available_credits`를 확인하세요.

### rate_limit_exceeded

**유형:** `rate_limit_error` · **HTTP 상태:** 429

요청이 너무 많습니다. 속도를 줄이고 윈도우가 재설정된 후 재시도하세요. `X-RateLimit-Reset` 응답 헤더와 [속도 제한](/developers/guides/rate-limits) 가이드를 참조하십시오.

### internal_error

**유형:** `internal_error` · **HTTP 상태:** 500

예상치 못한 오류가 발생했습니다. 이 문제가 지속되면 저희 쪽 문제이지 사용자분 탓이 아닙니다. 문제를 안정적으로 재현할 수 있다면 문의 시 해당 정보를 포함해 주시면 도움이 됩니다.

---

Source: https://imagetotable.ai/ko/developers/guides/errors