오류와 요청 한도

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

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

자주 만나는 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 응답에는 다음이 포함될 수 있습니다.

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

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

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

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

코드	의미	클라이언트 동작
`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`