---
title: 오류와 요청 한도
description: 공개 오류 봉투, request id, 요청 한도, 백프레셔 동작을 살펴보세요.
---

Sume는 구조화된 공개 오류를 반환합니다. 오류 본문에는 Sume 지원팀에 공유해도
안전한 request id가 들어 있습니다.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body, parameters, or headers.",
    "request_id": "req_...",
    "details": []
  }
}
```

## 자주 만나는 API 오류

| 상태 | 코드 | 의미 |
|---|---|---|
| `400` | `invalid_request` 또는 `bad_request` | 요청 본문, 쿼리, 경로, 헤더가 올바르지 않습니다. |
| `401` | `unauthorized` | API 키가 없거나 유효하지 않습니다. |
| `402` | `insufficient_credits` | 워크스페이스에 요청에 필요한 크레딧이 부족합니다. [크레딧 부족](#크레딧-부족)을 참고하세요. |
| `404` | `not_found` | 현재 워크스페이스에 해당 리소스가 없습니다. |
| `409` | `job_not_completed`, `job_not_cancelable` 또는 `job_generation_already_started` | 현재 상태에서는 요청한 Job 작업이 유효하지 않습니다. |
| `413` | `payload_too_large` | 요청 본문이 API 제한을 초과했습니다. |
| `429` | `rate_limited` | 현재 윈도에서 요청이 너무 많습니다. |
| `429` | `queue_full` | 워크스페이스의 생성 동시 실행 수와 큐 용량이 모두 찼습니다. |
| `503` | `provider_not_configured`, `provider_capacity_exceeded`, 또는 스토리지 설정 오류 | 런타임 의존성을 쓸 수 없거나 용량이 가득 찼습니다. |

## 크레딧 부족

모든 사용량은 크레딧 단위입니다. 워크스페이스 잔액으로 요청을 감당할 수 없으면
Sume는 프로바이더 작업이 시작되기 전에 `402 insufficient_credits`로 응답합니다.

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this request.",
    "request_id": "req_...",
    "details": { "required_credits": 150, "available_credits": 40 }
  }
}
```

`details.required_credits`는 요청에 필요한 크레딧이고,
`details.available_credits`는 워크스페이스가 지금 가진 크레딧입니다. 지갑이
프로비저닝되지 않은 조직 워크스페이스는 같은 `details`와 함께
`402 organization_wallet_not_provisioned`를 받습니다. 플랜을 업그레이드하거나
크레딧을 구매한 뒤 다시 시도하세요. [결제와 크레딧](/dashboard/credits)에서
살펴보세요.

## Request id

API는 응답 본문과 응답 헤더에 Sume request id를 노출합니다. 이슈를 보고할 때
함께 알려주세요. API 키, 서명된 URL, 원본 미디어 URL, 비공개 워크스페이스·사용자
ID는 포함하지 마세요.

## 요청 한도 헤더

공개 API 응답에는 다음이 포함될 수 있습니다.

```text
ratelimit-limit
ratelimit-remaining
ratelimit-reset
retry-after
```

`429`를 받으면 백오프하세요. `retry-after`가 있으면 그 값을 사용하세요.
`Idempotency-Key` 없이 안전하지 않은 제출 요청을 재시도하지 마세요.

`queue_full`은 일반적인 요청 한도와 다릅니다. 대기 중이거나 처리 중인 Job이
끝나거나 취소되기 전까지는 그 워크스페이스에서 유료 생성 Job을 더 받을 수 없다는
뜻입니다. 동시 실행 수가 찬 것 자체는 오류가 아닙니다. 큐 용량이 남아 있는 한
Sume는 유효한 Job을 `queued`로 접수합니다.
[생성 접수](/workflows/generation-admission)에서 살펴보세요.

## 프로바이더와 워커 백프레셔

프로바이더 작업이 접수되기 전에 용량이나 런타임 오류가 돌아올 수도 있습니다.

| 코드 | 의미 | 클라이언트 동작 |
|---|---|---|
| `provider_capacity_exceeded` | Sume의 프로바이더 디스패치 큐가 가득 찼습니다. | 같은 idempotency 키로 나중에 재시도하세요. |
| `provider_not_configured` | 이 런타임에서 프로바이더 실행을 쓸 수 없습니다. | 공격적으로 재시도하지 말고 카탈로그·런타임 상태를 확인하세요. |
| `job_ledger_not_configured` | Job 영속화를 쓸 수 없습니다. | 서비스 이용 불가로 처리하세요. |
| `image_not_fetchable`, `input_media_unreachable` 또는 스토리지 설정 오류 | Sume가 미디어를 안전하게 가져오거나 미러링하지 못했습니다. | 입력 미디어가 공개 HTTPS 이미지 URL인지 확인한 뒤 재시도하거나 request id와 함께 지원팀에 문의하세요. |
| `input_media_too_large` | 입력 이미지가 모델이 받는 크기보다 큽니다 (참조 이미지는 한 장에 30 MB까지, 7 MB가 넘는 이미지는 10장까지). | 더 작은 이미지를 보내세요. 같은 요청은 같은 이유로 실패합니다. |
| `reference_staging_failed` | Sume가 큰 참조 이미지를 모델에 넘길 준비를 하지 못했습니다. 생성은 일어나지 않았습니다. | request id와 함께 지원팀에 문의하세요. |

## Job 오류

실패한 Job은 카테고리, 단계, 재시도 가능 여부, retry-after 초, 공개 사유, 다음
동작 같은 공개 오류 메타데이터를 노출합니다. 내부 프로바이더 페이로드는 공개 API
필드가 아닙니다.

자주 나오는 Job 오류 카테고리는 다음과 같습니다.

| 카테고리 | 보통의 다음 동작 |
|---|---|
| `validation` | 입력을 고치세요. |
| `auth` | API 키와 워크스페이스 접근 권한을 확인하세요. |
| `quota` | 크레딧을 추가하거나(플랜 업그레이드 또는 크레딧 구매), 크레딧을 덜 사용하는 요청을 보내세요. |
| `queue` | 같은 idempotency 키로 나중에 재시도하세요. |
| `generation_unavailable` | 나중에 재시도하세요. |
| `generation_rejected` | 이벤트를 확인하고 지원되지 않는 입력을 고치세요. |
| `generation_timeout` | 상태를 폴링하거나 나중에 재시도하세요. |
| `runtime_unavailable` | 나중에 재시도하되 공격적으로 재시도하지 마세요. |
| `worker_timeout` | 상태를 폴링하거나 나중에 재시도하세요. |
| `internal` | 이벤트를 확인하고 request id·Job ID와 함께 지원팀에 문의하세요. |

미디어 런타임이 Sume 자체 인증 정보를 거부한 Job은 public reason `provider_auth_failed`(category `generation_unavailable`, 재시도 불가, next action `contact_support`)로 한 번만 실패해요. 타임아웃도 입력 문제도 아닌 Sume 설정 문제이니 재시도하지 마세요. HTTP 상태가 있는 실패는 `generation_timeout`으로 표시되지 않아요.

## 상태 값 목록

| 객체 | 값 |
|---|---|
| Job 상태 | `queued`, `processing`, `completed`, `failed`, `canceled` |
| 리소스 상태 | `processing`, `ready`, `failed`, `canceled`, `archived` |
| 웹훅 전달 상태 | `pending`, `delivering`, `delivered`, `retrying`, `failed`, `exhausted` |