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

# 오류

> 오류 형식과 코드, 재시도 기준이에요.

## 오류 형식

요청이 거절되면 항상 같은 모양으로 답해요.

```json theme={null}
{
  "error": {
    "code": "invalid_params",
    "message": "Check the request.",
    "request_id": "req_8f2a1c...",
    "details": [
      { "param": "aspect", "message": "Must be one of: 1:1, 16:9, 9:16, 4:3, 3:4." }
    ],
    "retryable": false,
    "retry_after_seconds": null
  }
}
```

| 필드 | 뜻 |
| - | - |
| `code` | 프로그램에서 구분할 때 쓰는 값이에요. |
| `message` | 사람이 읽는 설명이에요. 기본은 영어이고, `Accept-Language: ko`를 보내면 한국어예요. |
| `request_id` | 문의할 때 알려 주세요. 모든 응답의 `x-request-id` 헤더에도 있어요. |
| `details` | 항목별 문제처럼 더 자세한 내용이에요. 없으면 `null`이에요. |
| `retryable` | 같은 요청을 다시 보내도 되는지 알려줘요. |
| `retry_after_seconds` | 이만큼 기다린 뒤 다시 보내요. 없으면 `null`이에요. |

## 재시도 기준

`retryable`이 `true`일 때만 다시 보내요. `retry_after_seconds`가 있으면 그만큼 기다리고, 없으면 1초, 2초, 4초처럼 간격을 늘려 주세요. `POST /generations`는 같은 [`Idempotency-Key`](https://studio-docs.thezet.io/idempotency)로 보내야 두 번 청구되지 않아요.

## 코드

| 상태 | 코드 | 뜻과 해결 방법 |
| - | - | - |
| `400` | `invalid_request` | 요청 형식이 잘못됐어요. `details`를 확인해 주세요. |
| `400` | `invalid_params` | 모델에 없는 옵션이나 조합이에요. `details`에 항목별로 나와요. |
| `400` | `invalid_inputs` | 모델이 이 입력 조합을 받지 않아요. 메시지를 확인해 주세요. |
| `400` | `input_not_found` | 입력 파일을 찾을 수 없어요. 업로드 확인 전이거나, 지워졌거나, 다른 계정의 파일이에요. |
| `400` | `invalid_idempotency_key` | 키 형식이 잘못됐어요. |
| `400` | `invalid_range` | `GET /usage`의 기간이 잘못됐어요. `from`은 `to`보다 늦을 수 없고, 기간은 366일까지예요. |
| `400` | `invalid_size` | 파일 크기가 잘못됐어요. |
| `401` | `unauthorized` | 키가 없거나 잘못됐어요. [인증](https://studio-docs.thezet.io/authentication.md)을 봐 주세요. |
| `402` | `insufficient_balance` | 잔액이 부족해요. 충전한 뒤 같은 키로 다시 보내면 돼요. |
| `403` | `api_not_enabled` | 이 계정의 API 사용이 승인되지 않았어요. |
| `403` | `access_limited` | 이 계정은 아직 쓸 수 없어요. |
| `404` | `not_found` | 작업을 찾을 수 없어요. 다른 계정의 작업도 `404`예요. |
| `404` | `model_not_found` | 없는 모델이에요. `GET /models`를 확인해 주세요. |
| `404` | `upload_not_found` | 업로드를 찾을 수 없어요. 이미 지운 파일도 `404`예요. |
| `409` | `idempotency_conflict` | 같은 키로 내용이 다른 요청을 보냈어요. |
| `409` | `generation_not_cancelable` | 이미 시작했거나 끝난 작업이에요. |
| `409` | `generation_active` | 진행 중인 작업은 지울 수 없어요. 끝난 뒤 다시 시도해 주세요. |
| `409` | `upload_incomplete` | 파일이 아직 도착하지 않았어요. |
| `409` | `upload_in_use` | 진행 중인 작업이 쓰는 파일이에요. 끝난 뒤 다시 시도해 주세요. |
| `413` | `payload_too_large` | 요청 본문이 1MB를 넘어요. |
| `413` | `too_large` | 파일이 20MB를 넘어요. |
| `415` | `unsupported_media_type` | 본문은 `application/json`이어야 해요. |
| `415` | `unsupported_type` | PNG, JPG, WebP 이미지만 올릴 수 있어요. |
| `429` | `rate_limited` | 호출 한도를 넘었어요. [한도](https://studio-docs.thezet.io/limits.md)를 봐 주세요. |
| `429` | `concurrency_limit` | 동시 실행 한도를 넘었어요. [한도](https://studio-docs.thezet.io/limits.md)를 봐 주세요. |
| `500` | `internal` | 저희 쪽 문제예요. 다시 시도해 주세요. |
| `501` | `storage_disabled` | 파일 저장소를 쓸 수 없어요. 저희에게 알려 주세요. |
| `503` | `model_unavailable` | 지금은 이 모델을 쓸 수 없어요. 잠시 후 다시 시도하거나 다른 모델을 골라 주세요. |

## 작업 실패

요청은 받았지만 작업이 실패하면 HTTP 오류가 아니라 작업의 `status`가 `failed`가 되고 금액을 돌려드려요. 이유는 `error.code`에 있어요.

| 코드 | 뜻 | 할 일 |
| - | - | - |
| `content_rejected` | 콘텐츠 정책에 걸렸어요. | 프롬프트나 입력 이미지를 바꿔 주세요. 그대로 다시 보내면 또 거절될 수 있어요. |
| `generation_failed` | 그 밖의 이유로 실패했어요. | 다시 시도해 주세요. 새 작업이니 새 `Idempotency-Key`를 써 주세요. |

앞으로 코드가 늘어날 수 있어요. 모르는 코드는 `generation_failed`처럼 처리해 주세요.

## MCP

[MCP](https://studio-docs.thezet.io/mcp.md) 도구에서만 나오는 코드예요.

| 상태 | 코드 | 뜻과 해결 방법 |
| - | - | - |
| `400` | `price_over_limit` | 작업 가격이 `max_spend_usd`를 넘어요. 시작하지 않았고 청구되지 않았어요. |
| `400` | `wrong_tool` | 이 도구로 쓸 수 없는 모델이에요. 이미지 모델은 `generate_image`, 영상 모델은 `generate_video`를 써요. |
| `401` | `api_key_not_accepted` | 이 주소는 로그인으로만 연결해요. API 키는 `https://api.studio.thezet.io/mcp`에 보내요. |
| `403` | `app_disconnected` | 설정의 연결된 앱에서 연결을 해제했어요. 같은 화면에서 다시 허용해 주세요. |
| `503` | `oauth_disabled` | 지금은 로그인으로 연결할 수 없어요. 잠시 후 다시 시도해 주세요. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.