---
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 작업이 유효하지 않습니다. |
| `413` | `payload_too_large` | 요청 본문이 API 제한을 초과했습니다. |
| `429` | `rate_limited` | 현재 윈도에서 요청이 너무 많습니다. |
| `429` | `queue_full` | 워크스페이스의 생성 동시 실행 수와 큐 용량이 모두 찼습니다. |
| `503` | `provider_not_configured`, `provider_capacity_exceeded`, 또는 스토리지 설정 오류 | 런타임 의존성을 쓸 수 없거나 용량이 가득 찼습니다. |

## 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 영속화를 쓸 수 없습니다. | 서비스 이용 불가로 처리하세요. |
| `media_fetch_failed` 또는 스토리지 설정 오류 | Sume가 미디어를 안전하게 가져오거나 미러링하지 못했습니다. | 입력 미디어가 공개 HTTPS 이미지 URL인지 확인한 뒤 재시도하거나 request id와 함께 지원팀에 문의하세요. |

## Job 오류

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

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

| 카테고리 | 보통의 다음 동작 |
|---|---|
| `validation` | 입력을 고치세요. |
| `auth` | API 키와 워크스페이스 접근 권한을 확인하세요. |
| `quota` | 잔액을 충전하거나 요청 비용을 낮추세요. |
| `provider_unavailable` | 나중에 재시도하세요. |
| `provider_rejected` | 이벤트를 확인하고 지원되지 않는 입력을 고치세요. |
| `provider_timeout` | 상태를 폴링하거나 나중에 재시도하세요. |
| `media_mirror_failed` | 이벤트를 확인하세요. 결과에 Sume 미디어 URL이 없을 수 있습니다. |
| `worker_timeout` | 상태를 폴링하거나 나중에 재시도하세요. |
| `internal` | 이벤트를 확인하고 request id·Job ID와 함께 지원팀에 문의하세요. |

## 상태 값 목록

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