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

# 오류 및 디버깅

> Krea API의 HTTP 오류와 실패한 작업의 코드: 응답 형식, 상태 코드, 동시성 429, 지원팀에 보낼 정보를 안내합니다.

호출은 두 지점에서 실패할 수 있습니다. 요청이 HTTP 오류와 함께 즉시 거부되거나, 접수된 뒤 나중에 `status: "failed"`로 끝날 수 있습니다. 실패하거나 취소된 작업은 청구되지 않습니다. 완료된 작업에 대해서만 요금이 부과됩니다. 노드 앱에서는 앱 자체의 작업은 청구되지 않습니다. 각 생성 노드 또는 LLM 노드는 해당 노드의 작업이 완료될 때 청구됩니다. 실패가 발생해도 병렬 노드나 다른 분기는 취소되지 않으므로, 앱이 이미 실패한 뒤에 완료된 노드도 청구되며 이 요금은 환불되지 않습니다. 실패했거나, 취소되었거나, 시작되지 않은 노드는 청구되지 않습니다. [API 키 및 청구](https://www.krea.ai/docs/ko/developers/api-keys-and-billing.md)를 참고하세요.

## 요청 시점 오류와 실패한 작업

**요청 시점 오류**는 `4xx` 또는 `5xx` 상태를 반환합니다. 작업은 생성되지 않습니다. 아래 설명에 따라 본문을 읽으세요.

**실패한 작업**은 제출 시점에 성공 상태를 반환합니다. [GET `/jobs/{id}`](https://www.krea.ai/docs/ko/developers/job-lifecycle)를 폴링하거나 [웹훅](https://www.krea.ai/docs/ko/developers/webhooks.md)을 기다리세요. 작업이 끝나면 `status`가 `"failed"`이고, 실패 정보는 최상위 `error` 객체에 담깁니다. 실패한 작업에서는 `result`를 읽지 마세요. 이 필드는 생략되거나 `null`입니다. `result`에는 `status`가 `"completed"`일 때만 출력이 담깁니다. `cancelled` 작업에는 `result`도 `error`도 없습니다.

`error.code`를 기준으로 분기하세요. `message`는 생략될 수 있으며, `provider_error`와 `internal`의 경우 공급자가 보낸 자유 형식 텍스트입니다. `message`를 파싱하지 마세요.

```javascript theme={"theme":{"light":"github-light-default","dark":"vesper"}}
if (job.status === "failed") {
  switch (job.error?.code ?? "internal") {
    case "content_policy":
    case "model_unavailable":
      // 같은 요청을 재시도하면 다시 실패할 가능성이 높습니다. 입력이나 모델을 바꾸세요.
      break;
    case "insufficient_balance":
      // API 잔액을 충전한 뒤 다시 제출하세요.
      break;
    default:
      // timeout, auto_cancelled, provider_error, internal, node_app_node_failed,
      // 또는 알 수 없는 코드: 백오프를 적용해 다시 제출하세요.
  }
}
```

## 응답 본문

generate, jobs, assets, styles, 노드 앱에서는 본문이 JSON일 때 `message ?? error`를 읽으세요. 두 필드 중 하나에 요약이 담깁니다. 일부 `5xx` 본문은 JSON이 아닙니다. 예를 들어 `502`의 본문은 일반 텍스트 `error code: 502`일 수 있습니다. 방어적으로 파싱하세요. 본문이 JSON이 아니면 HTTP 상태를 기준으로 분기하세요.

대부분의 실패는 `{ "message": "..." }`를 사용하며, 추가 필드(`limit`, `jobType`, `modelAccessDenial`)가 붙기도 합니다. 잘못된 JSON과 아래의 일부 핸들러는 대신 `{ "error": "..." }`를 사용합니다.

`/mcp` 같은 MCP 엔드포인트는 이 페이지의 HTTP 본문이 아니라 JSON-RPC 오류 `{ "jsonrpc", "id", "error": { "code", "message" } }`를 반환합니다.

### `Accept: application/json` 보내기

> [!WARNING]
>
> `Accept: application/json`이 없으면 일부 오류가 HTML 페이지로 반환되어 JSON 파서가 실패합니다.

`401`과 `404`를 포함한 `{ "message" }` 오류는 `Accept`가 `application/json` 또는 `*/*`일 때 JSON입니다. `Accept`가 없거나 `text/html`이면 이 상태들은 HTML 페이지(`Content-Type: text/html`)로 반환되어 JSON 파서가 실패합니다.

이는 `Accept` 헤더를 보내지 않는 클라이언트에 중요합니다. Python의 `urllib`가 그 예입니다. curl과 Node의 `fetch`는 기본적으로 `Accept: */*`를 보내므로, `Accept`를 재정의하지 않는 한 둘 다 JSON을 받습니다.

인증되지 않은 `POST /generate/...`, `GET /jobs/{id}`, `GET /styles`, `GET /assets`는 `*/*`와 `application/json`에 대해 `401` `{"message":"Unauthorized"}`를 반환하고, `Accept`가 없거나 `text/html`이면 HTML 페이지를 반환합니다. 알 수 없는 id로 인증된 `GET /jobs/{id}`를 호출해도 상태만 다를 뿐 동일하게 동작합니다. `Accept`가 JSON을 요청하면 `404` JSON `{"message":"Job not found or unauthorized"}`를, `Accept`가 없으면 `404` `text/html`을 반환합니다.

잘못된 JSON(`400`)과 유효성 검사(`422`)는 `{ "error" }`를 사용하며 `Accept`가 없어도 JSON으로 유지됩니다. 제거된 필드의 `422`, 종료(sunset) `410`, Zero Data Retention `402`, 노드 앱의 `{ "error" }` 응답, 매핑된 [Agent operation API](#agent-operation-api) 오류도 마찬가지입니다. `POST /generate/...` 작업 접수 시의 `402`와 `429`도 브라우저의 `Accept`인 경우를 포함해 JSON입니다.

`413`과 `500`은 `{ "message" }`를 사용하며 `401`, `404`와 마찬가지로 `Accept`를 따릅니다.

### 유효성 검사 (`422`)

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{
  "error": "Validation failed",
  "details": [
    {
      "field": "width",
      "message": "Too small: expected number to be >0",
      "code": "too_small"
    },
    {
      "field": "",
      "message": "Unrecognized key: \"foo\"",
      "code": "unrecognized_keys"
    },
    {
      "field": "prompt",
      "message": "Enter a prompt.",
      "code": "custom"
    }
  ]
}
```

`details`에는 모든 문제가 나열됩니다. `field`는 `.`으로 연결한 경로입니다(`"image_style_references.0.url"`). 객체 수준 오류는 위의 알 수 없는 키처럼 빈 문자열을 사용합니다. 알 수 없는 키가 여러 개이면 `Unrecognized keys: ...`와 동일한 빈 `field`가 생성됩니다. `expected`는 `code`가 `"invalid_type"`일 때만 추가됩니다.

잘못된 `X-Webhook-URL` 헤더도 이와 같은 `422`를 사용합니다.

잘못된 쿼리 파라미터로 `GET /jobs`를 호출해도 이 `422`를 반환합니다. `400`이 아닙니다.

도구 내부에서 Zero Data Retention 입력 검사가 실패하면 `message`에 설명을 담아 `422`를 반환합니다(`{ "message" }` 형식이므로 `Accept`가 중요합니다). [Zero Data Retention](https://www.krea.ai/docs/ko/developers/zdr.md)을 참고하세요.

### 제거 및 지원 중단된 필드 (`422`)

제거된 `batchSize` / `batch_size` 필드는 다른 형태의 `422`를 사용합니다. `details` 배열은 없습니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{
  "error": "invalid_request",
  "reason": "removed_field",
  "field": "batchSize",
  "message": "Generation batch size is no longer supported. Submit one request per output.",
  "value": 2
}
```

`batch_size`도 같은 방식으로 제거되었습니다. `field`는 보낸 이름 그대로입니다.

지원 중단된 필드 별칭은 `reason` `"deprecated_field"` 또는 `"conflicting_fields"`를 사용하며, 해당하는 경우 `replacement`, `sunset_date`, `migration_url`이 함께 포함됩니다. `error`와 `reason`을 기준으로 분기하세요. 사람에게 보여 줄 문장은 `message`입니다.

### 종료된 모델 (`410`)

종료일이 지난 모델은 `Deprecation: true`와 `Sunset` 헤더(RFC 1123 날짜)와 함께 `410`을 반환합니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{
  "error": "model_unavailable",
  "reason": "deprecated",
  "message": "The model '<path>' was deprecated on <sunsetDate>. <reason> Use '<replacement>' instead.",
  "sunset_date": "YYYY-MM-DD",
  "replacement": "<optional>",
  "migration_url": "<optional>"
}
```

`error`는 고정 값 `"model_unavailable"`입니다. 권장 대체 모델이 없으면 `replacement`와 `migration_url`은 생략됩니다. 같은 모델로 재시도하면 계속 `410`이 반환됩니다. `replacement`가 설정되어 있으면 해당 모델로 전환하고, [Deprecations](https://www.krea.ai/docs/ko/developers/deprecations.md)를 참고하세요.

지원 중단되었지만 아직 사용 가능한 모델은 오류를 포함한 모든 응답에 `Deprecation`과 `Sunset`을 보냅니다. 지원 중단된 필드 별칭을 사용할 때도 해당 `422`를 포함해 동일합니다. 마이그레이션 가이드가 있으면 `Link: <migration_url>; rel="deprecation"` 헤더도 함께 전송됩니다.

## 상태 코드

| 상태 | 의미 |
| - | - |
| `400` | generate 본문이 유효한 JSON이 아니거나, 노드 앱 입력 URL을 사용할 수 없거나, asset 또는 노드 앱 파라미터가 잘못되었습니다. 노드 앱 execute에서 잘못된 JSON은 `500`입니다. |
| `401` | 자격 증명이 없거나 유효하지 않습니다. |
| `402` | 작업이 시작되기 전에 요청이 거부되었습니다. [402](#402-payment-required)를 참고하세요. |
| `403` | 호출자는 인증되었지만 이 리소스를 사용할 권한이 없습니다. |
| `404` | 일치하는 경로가 없거나, 모델 경로를 알 수 없거나 사용할 수 없거나, 작업, asset, 스타일 또는 노드 앱이 없습니다. |
| `405` | 이 경로에서 허용되지 않는 HTTP 메서드입니다. |
| `410` | 모델이 종료되었습니다. [종료된 모델](#sunset-models-410)을 참고하세요. |
| `413` | 요청 본문이 너무 큽니다. [413](#413-payload-too-large)을 참고하세요. |
| `422` | 유효성 검사에 실패했거나, 제거 또는 지원 중단된 필드를 보냈거나, 입력이 영구적으로 거부되었습니다. |
| `429` | 동시성 상한을 초과했고 작업을 백로그할 수 없습니다. 상한은 근사값입니다. |
| `500` | 처리되지 않은 서버 오류입니다. `{ "message": "Internal Error" }`. 예외 텍스트는 없습니다. `Accept`를 따릅니다. |
| `502`, `504` | 재시도할 수 있습니다. `502`는 JSON이 아닌 Cloudflare 일반 텍스트 `error code: 502`로 도착하므로 상태 코드를 기준으로 분기하세요. `504`도 일반 텍스트일 수 있습니다. [입력 다운로드](#input-downloads)를 참고하세요. |

### `400`

generate에서 잘못된 JSON은 `Accept` 헤더 없이도 항상 JSON입니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{
  "error": "Invalid JSON: Expected property name or '}' in JSON at position 1 (line 1 column 2)"
}
```

노드 앱 execute는 사용할 수 없는 입력 URL에 대해 `{ "error" }`를 사용합니다: `Invalid URL for input "<key>"` 또는 `Failed to download URL for <key>: …`. 다운로드 메시지는 일시적인 실패도 포함하므로, generate와 달리([입력 다운로드](#input-downloads) 참고) 노드 앱의 다운로드 실패는 항상 `400`입니다. URL이 유효하다면 한 번 재시도하세요.

`POST /node-apps/{id}/execute`에서 잘못된 JSON은 위의 generate `400`이 아닙니다. 예외 텍스트 없이 `500` `{ "message": "Internal Error" }`가 되며 `Accept`를 따릅니다.

assets와 노드 앱의 다른 `400` 응답은 짧은 설명이 담긴 `{ "message": "..." }`입니다. 예를 들어 presigned 업로드의 `No file provided`나 노드 앱 버전의 `Invalid pagination parameters`가 있습니다. asset 업로드가 실패하면 업로드 서비스의 상태(`400`, `401`, `404` 또는 `500`)가 그대로 전달되며, 응답 텍스트가 `message`에 담길 수 있습니다. 이 텍스트는 JSON 문자열인 경우도 있습니다. `GET /jobs`의 잘못된 쿼리 파라미터는 `400`이 아니라 [`422`](#validation-422)입니다.

### `401`

generate, jobs, assets, styles, 노드 앱:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{ "message": "Unauthorized" }
```

presigned 업로드는 `{ "message": "Presigned upload URL expired" }` 또는 `{ "message": "Invalid presigned upload URL" }`를 반환합니다.

### `402` 결제 필요

API 잔액이 작업 비용을 충당하지 못하는 API 청구 클라이언트(API 키, 또는 API 키를 사용하는 MCP)의 경우:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{
  "message": "Your API balance is separate from your workspace compute balance. Please top up your API balance to continue using the API."
}
```

[krea.ai/app/api/ ↗](https://krea.ai/app/api/)에서 충전하세요. 진행 중인 작업은 완료됩니다. [API 키 및 청구](https://www.krea.ai/docs/ko/developers/api-keys-and-billing.md)를 참고하세요.

공개 API의 기타 `402` `message` 값:

| `message` | 발생 시점 |
| - | - |
| `This tool is not available on your current plan.` | 플랜 또는 워크스페이스에서 이 모델의 동시 작업이 허용되지 않습니다. |
| `MEMBER_USAGE_LIMIT_REACHED` | 플랜이 구성원 사용 한도를 적용하며, 이 구성원의 예산을 초과하게 됩니다. |
| `WORKSPACE_USAGE_LIMIT_REACHED` | 플랜이 구성원 사용 한도를 적용하며, 워크스페이스 예산을 초과하게 됩니다. |
| `MEMBER_LIMIT_VIOLATION` | 워크스페이스의 구성원 수가 플랜에서 허용하는 수보다 많습니다. |
| `K3_ULTRA_ACCESS_REQUIRED` | Krea 3 Ultra가 없는 플랜에서 Krea 3을 `thinking_mode` `"ultra"`(또는 레거시 `"max"`)와 이미지 참조로 호출했습니다. 이미지 참조가 없으면 Ultra는 `"fast"`로 실행됩니다. |
| `ENHANCER_RESOLUTION_LIMIT_REACHED` | 업스케일 크기가 무료 플랜에서 허용하는 범위를 넘습니다. |

Zero Data Retention이 활성화되지 않은 워크스페이스에서 Zero Data Retention으로 generate를 호출하면 다음 본문을 반환하며, 항상 JSON입니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{ "error": "Zero data retention is not enabled for this workspace." }
```

[Agent operation API](#agent-operation-api)는 자체 `402` 본문을 사용합니다. 이 경우 API 잔액이 아니라 워크스페이스 컴퓨트 잔액이 사용됩니다.

### `403`

| `message` 또는 `error` | 발생 시점 |
| - | - |
| `Use an API key or a plugin session` | API 키나 OAuth 또는 플러그인 세션 없이 Realtime을 호출했습니다. `{ "message" }`. |
| `This endpoint needs a workspace service API key` | Usage API에서 자격 증명이 워크스페이스 서비스 API 키가 아닙니다. `{ "message" }`. |
| `Your plan is not entitled to the usage API` | Usage API에서 플랜에 사용 권한이 없습니다. `{ "message" }`. |
| `FEATURE_RESTRICTED` | 모델 정책에 의한 거부입니다. 본문에 `modelAccessDenial`도 포함됩니다. `{ "message" }`. |
| `MODEL_ACCESS_REQUIRED` | 내부 전용 모델입니다. `{ "message" }`. |
| `This node app cannot be used via the API.` | 노드 앱 execute. `{ "error" }`, 항상 JSON입니다. |
| `Free users cannot run node apps` | 무료 플랜 워크스페이스에서 노드 앱 execute를 호출했습니다. `{ "message" }`. |
| `You do not own this style` | 소유하지 않은 스타일을 변경하거나 공유하려 했습니다. `{ "message" }`. |

### `404`

모든 `404`는 `{ "message" }`입니다. 예를 들어 알 수 없는 작업 id의 경우:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{ "message": "Job not found or unauthorized" }
```

`Accept` 헤더가 없으면 이 응답들은 HTML이 됩니다. 단, 키나 플랜으로 사용할 수 없는 모델에 대한 `Endpoint not found`는 예외로 항상 JSON입니다. `Accept` 없이 알 수 없는 id로 인증된 `GET /jobs/{id}`를 호출하면 `404` `text/html`입니다.

| `message` | 발생 시점 |
| - | - |
| `Not Found` | 경로와 일치하는 라우트가 없습니다. |
| `Endpoint not found` | `/generate` 아래의 모델 경로를 알 수 없거나, 이 API 키 또는 플랜으로 사용할 수 없습니다. |
| `Job not found or unauthorized` | 작업 id가 없거나 유효하지 않습니다. `DELETE /jobs/{id}`도 포함됩니다. |
| `Asset not found` | asset이 없습니다. |
| `Style not found` | 스타일이 없습니다. 소유하지 않은 스타일을 변경하거나 공유하면 `Style not found or you are not the owner`입니다. |
| `Node app not found` | 노드 앱이 없습니다. |
| `Workspace not found` | Usage API에서 워크스페이스가 없습니다. |

알 수 없는 Agent operation도 Agent의 `{ "error", "code" }` 형식이 아니라 `404` `{ "message": "Endpoint not found" }`입니다.

### `405`

본문은 JSON이 아니라 `Content-Type` 헤더가 없는 일반 텍스트이며, `Accept`가 `application/json`이어도 마찬가지입니다. 텍스트는 메서드 뒤에 ` method not allowed`가 붙은 형태입니다(예: `GET method not allowed`). `Allow` 헤더에 해당 경로가 허용하는 메서드가 나열됩니다.

### `413` 페이로드 초과

너무 큰 요청 본문은 `413`으로 거부됩니다. API 자체에서 반환하는 본문은 `Accept`를 따릅니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{ "message": "Payload Too Large" }
```

매우 큰 본문은 API에 도달하기 전에 HTML `413` 페이지로 거부될 수 있습니다. 파일을 인라인으로 보내지 마세요. `POST /assets`로 파일을 업로드하고 반환된 URL을 generate 요청에 전달하세요.

### 입력 다운로드

호스트가 `404` 또는 `410`을 반환하면 영구적인 `422`입니다. 본문은 JSON이며 `Accept`가 중요합니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{ "message": "Input file rejected: fetching <url> returned HTTP 404" }
```

호스트가 `410`을 반환하면 같은 문장에 `410`이 들어갑니다. 그 밖의 영구적인 거부는 `Input file rejected: …`를 사용합니다.

재시도할 수 있는 다운로드 실패는 `502` 또는 `504`입니다. 본문이 아니라 상태 코드를 기준으로 분기하고 재시도하세요.

| 상태 | 받게 되는 응답 | 재시도 여부 |
| - | - | - |
| `422` | 호스트가 `404`를 반환하면 JSON `{ "message": "Input file rejected: fetching <url> returned HTTP 404" }`. 호스트가 `410`을 반환하면 같은 문장에 `410`이 들어갑니다. | 아니요. 영구적인 실패입니다. |
| `502` | `Content-Type: text/plain; charset=UTF-8`의 Cloudflare 일반 텍스트 `error code: 502`. 파일 호스트가 `503`, `500` 또는 `429`를 반환하는 경우와 도메인을 확인할 수 없는 경우에 확인되었습니다. | 예. 상태 코드를 기준으로 분기하세요. |
| `504` | 실제 환경에서 테스트되지 않았습니다. 이 역시 Cloudflare 일반 텍스트로 도착할 수 있습니다. | 예. 상태 코드를 기준으로 분기하세요. |

같은 URL에서 `502`가 계속 반복된다면 URL이 차단되었거나 손상되었을 가능성이 높습니다. URL을 바꾸세요.

3D 내보내기 변환 실패도 `502`입니다. 이 경로는 실제 환경에서 테스트되지 않았으므로 본문이 Cloudflare 일반 텍스트 `error code: 502`로 도착할 수도 있습니다. 상태 코드를 기준으로 분기하고 재시도하세요. 같은 모델 URL에서 `502`가 계속 반복된다면 URL이 차단되었거나 손상되었을 가능성이 높습니다.

### `429` 동시성

작업을 백로그할 수 없으면, 동시성 상한을 넘은 요청은 `Content-Type: application/json`과 함께 `429`로 거부될 수 있습니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{
  "message": "CONCURRENCY_LIMIT_REACHED",
  "limit": 4,
  "jobType": "k2"
}
```

`limit`은 이 종류의 작업에 대한 동시성 상한입니다. 워크스페이스 단위가 아니라 사용자 단위로 계산됩니다. 근사값이므로 짧은 순간에 몰린 요청은 상한을 넘어서도 접수될 수 있습니다. 따라서 `limit + 1`번째 요청이 실패할 것이라고 가정하지 마세요. `jobType`은 공개 모델 경로가 아니라 내부 작업 분류입니다. 이 값을 기준으로 분기하지 마세요.

Krea 2는 공유 큐가 가득 찼을 때 `limit`이나 `jobType` 없이 `{ "message": "CONCURRENCY_LIMIT_REACHED" }`만 반환할 수도 있습니다. 이는 사용자의 상한 때문이 아닙니다. 백오프 후 재시도하세요.

백로그는 플랜에 포함되어 있고(Pro 이상), 모델이 지원하며, 요청이 [Zero Data Retention](https://www.krea.ai/docs/ko/developers/zdr.md)이 아닐 때만 적용됩니다. Krea 2 요청은 현재 어떤 플랜에서도 백로그되지 않으므로 상한을 넘으면 `429`를 반환합니다. 백로그가 적용되면 추가 작업은 `status: "backlogged"`로 접수되고 슬롯이 비면 시작됩니다. 별도의 백로그 상한은 없습니다. [Rate Limits](https://www.krea.ai/docs/ko/developers/rate-limits.md)를 참고하세요.

API는 `Retry-After`나 `X-RateLimit-*`를 보내지 않습니다. 응답에는 `cf-ray`가 포함됩니다. `429`를 받으면 진행 중인 작업이 끝난 뒤(`GET /jobs/{id}`를 폴링하거나 웹훅 사용) 지수 백오프로 재시도하세요.

나중에 완료된 작업으로 잔액이 소진되면, 백로그에 남아 있던 작업은 `error.code` `"insufficient_balance"`로 실패합니다. 이는 HTTP `402`가 아니라 실패한 작업입니다. 이러한 작업은 웹훅을 보내지 않으므로, 백로그된 작업은 `GET /jobs/{id}`로 폴링하세요.

## Agent operation API

`POST /agent/{operation}`과 `GET /agent/session/{sessionId}`는 `{ "error", "code"?, "allowedModels"? }`를 반환합니다. `error`만 필수입니다. `allowedModels`는 camelCase입니다. 접수된 뒤 실패한 턴은 이러한 HTTP 오류가 아니라 세션의 `status: "failed"`로 표시됩니다. [Agent](https://www.krea.ai/docs/ko/developers/agent.md)를 참고하세요.

| 상태 | 본문 |
| - | - |
| `400` | `{ "error": "Invalid JSON body" }` |
| `401` | `{ "error": "Unauthorized" }` |
| `402` | `{ "error": "Insufficient compute balance for an Agent turn", "code": "compute_limit" }` 또는 `{ "error": "Free plan Agent message limit reached. Upgrade to keep using the Agent", "code": "free_message_limit" }`. |
| `403` | `{ "error": "Model is not included in the workspace plan", "code": "model_not_entitled", "allowedModels": ["..."] }`. |
| `404` | 알 수 없는 operation: `{ "message": "Endpoint not found" }`. 그 외에는 `{ "error": "Session not found or not accessible", "code": "not_found" }` 또는 `{ "error": "<file reference error>", "code": "attachment_not_found" }`. |
| `409` | `{ "error": "...", "code": "conflict" }`. |
| `422` | 잘못된 입력: [유효성 검사](#validation-422)와 같은 `{ "error": "Validation failed", "details": [...] }`. 그 밖의 매핑된 오류는 `{ "error": "<message>" }`이며, 코드가 있으면 `code`가 추가됩니다. 데스크톱 앱 연결이 끊긴 경우에는 `code`가 없고, 메시지가 `That desktop app is not connected`로 시작합니다. |

인식되지 않는 Agent 오류 코드도 `{ "error", "code" }`와 함께 `422`입니다. 알 수 없는 operation의 `404`와 처리되지 않은 `500`은 `{ "message" }`를 사용하며 `Accept`를 따릅니다.

## 실패한 작업의 `error.code`

`GET /jobs`와 `GET /jobs/{id}`는 `status`가 `"failed"`일 때만 `error`를 설정합니다. 사용할 수 있는 `result`는 없습니다:

```json theme={"theme":{"light":"github-light-default","dark":"vesper"}}
{
  "status": "failed",
  "error": {
    "code": "content_policy",
    "message": "An external provider's moderation systems rejected the generation."
  }
}
```

> [!WARNING]
>
> `error.code`를 기준으로 분기하세요. `message`는 절대 파싱하지 마세요.
>
> `message`는 생략될 수 있습니다. `provider_error`와 `internal` 메시지는 자유 형식이며, `internal` 메시지는 `failed to download media from the provided URL`처럼 공급자의 원문 텍스트일 수 있습니다. 인식하지 못하는 `code`는 모두 `internal`로 취급하세요.

| `code` | `message` | 조치 방법 |
| - | - | - |
| `content_policy` | `Krea's moderation systems rejected the generation.` 또는 `An external provider's moderation systems rejected the generation.` | 프롬프트나 입력을 바꾸세요. 같은 요청은 다시 거부될 가능성이 높습니다. |
| `timeout` | `An external provider did not complete the generation in sufficient time.` | 작업을 재시도하세요. |
| `insufficient_balance` | 생략됩니다. 노드 앱은 대신 `You are out of compute units. Add more compute units to continue running this node app.`를 반환할 수 있습니다. | 충전한 뒤 다시 제출하세요. 이 작업은 앞서 접수되었으며, HTTP 호출이 `402`를 반환한 것이 아닙니다. |
| `auto_cancelled` | `Job repeatedly failed healthchecks and was automatically cancelled.` | 작업을 다시 제출하세요. |
| `model_unavailable` | 대개 공급자 자체의 텍스트입니다. 텍스트가 없으면 `The provider retired this model. It no longer accepts new generations.` | 이 모델 호출을 중단하세요. [Deprecations](https://www.krea.ai/docs/ko/developers/deprecations.md)에 대체 모델이 있으면 사용하세요. |
| `provider_error` | 대개 공급자 자체의 텍스트입니다. | 백오프를 적용해 재시도하세요. |
| `internal` | 자유 형식이거나 생략됩니다. | 나중에 재시도하세요. 지원팀에 문의할 때는 `job_id`를 알려 주세요. |
| `node_app_node_failed` | `Node "<type>" failed: <detail>` 또는 `Node "<type>" failed.` | `message`를 읽으세요. 노드에 타임아웃 같은 일시적인 문제가 있었다면 앱을 다시 실행하세요. 그렇지 않으면 먼저 해당 노드를 수정하세요. 앱 자체의 작업은 청구되지 않습니다. 각 생성 노드 또는 LLM 노드는 해당 노드의 작업이 완료될 때 청구됩니다. 실패가 발생해도 병렬 노드나 다른 분기는 취소되지 않으므로, 앱이 이미 실패한 뒤에 완료된 노드도 청구되며 이 요금은 환불되지 않습니다. 실패했거나, 취소되었거나, 시작되지 않은 노드는 청구되지 않습니다. 노드 id와 노드 유형은 공개 작업 객체에 포함되지 않습니다. |

실패한 작업의 웹훅 전송은 `error`를 포함해 동일한 작업 객체를 사용합니다. 취소된 작업의 전송에는 `error`가 없습니다. 256 KiB보다 큰 페이로드는 전송되지 않으며 해당 작업에 대한 이후 전송도 이루어지지 않으므로, 대신 `GET /jobs/{id}`를 폴링하세요. 본문을 신뢰하기 전에 서명을 검증하세요. [웹훅](https://www.krea.ai/docs/ko/developers/webhooks.md)을 참고하세요.

## 디버깅

Krea 요청 ID 헤더는 없습니다. 대신 모든 응답에 Cloudflare의 `cf-ray` 헤더가 포함됩니다. `Retry-After`나 `X-RateLimit-*` 헤더는 전송되지 않습니다.

[support@krea.ai](mailto:support@krea.ai)로 문의할 때는 다음을 포함하세요:

* 호출이 작업을 생성했거나 작업을 대상으로 한 경우 `job_id`
* 시각과 엔드포인트
* 요청 시점 오류의 경우 `cf-ray` 값

`Access-Control-Allow-Origin`은 `*`입니다. generate, jobs, assets, styles, 노드 앱에서는 `Access-Control-Expose-Headers`가 설정되어 있지 않으므로, 브라우저의 `fetch`로는 `cf-ray`, `Deprecation`, `Sunset`을 읽을 수 없습니다. 네트워크 로그나 서버 측 클라이언트에서 `cf-ray`를 복사하세요.

모델이 호출을 더 이상 받지 않게 되기 전에, 모든 응답에서 `Deprecation`과 `Sunset`을 확인하세요. [Deprecations](https://www.krea.ai/docs/ko/developers/deprecations.md)를 참고하세요.

## 다음 단계

> **[작업 수명 주기](https://www.krea.ai/docs/ko/developers/job-lifecycle.md)**
>
> 작업이 완료, 실패 또는 취소될 때까지 상태 폴링하기

> **[웹훅](https://www.krea.ai/docs/ko/developers/webhooks.md)**
>
> 실패한 작업 전송의 서명 검증하기

> **[요청 한도](https://www.krea.ai/docs/ko/developers/rate-limits.md)**
>
> 추가 작업이 백로그되는 경우와 429를 반환하는 경우

> **[API 키 및 청구](https://www.krea.ai/docs/ko/developers/api-keys-and-billing.md)**
>
> 402 이후 API 잔액 충전하기


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