Sume API 오류와 요청 한도: 오류 코드, 429, 재시도 시점

Sume API의 모든 오류는 하나의 JSON 봉투로 돌아옵니다. 분기에 쓸 안정적인 소문자 code, 사람이 읽는 message, Sume 지원팀에 공유해도 안전한 request_id가 들어 있습니다. 요청 한도는 API 키별·분당으로 적용되고 읽기와 쓰기 예산이 따로 있으며, 429 queue_full은 요청을 너무 많이 보냈다는 뜻이 아니라 생성 용량이 가득 찼다는 뜻입니다.

아래 코드와 한도는 Sume의 오류와 요청 한도 (영문) 페이지와 Formats 오류와 비용 (영문) 레퍼런스를 바탕으로 합니다.

Sume 오류 응답은 어떤 모양인가요?

먼저 HTTP 상태로 분기하고, 그다음 code로 분기하세요. 봉투에는 코드 말고도 다음 정보가 담깁니다.

• code는 switch로 분기할 안정적인 토큰이며 ^[a-z0-9_]+$ 형식을 따릅니다. message는 사람이 읽도록 쓰였고 바뀔 수 있습니다. 로그에는 남기되 매칭에는 절대 쓰지 마세요.
• request_id는 x-sume-request-id 헤더로도 전달됩니다.
• retryable과 retry_after_seconds는 같은 요청을 다시 보내면 성공할 수 있는지, 그 전에 얼마나 기다려야 하는지 알려 줍니다.
• next_action은 authenticate, fix_input, add_funds, retry_later, poll_status, inspect_events, contact_support 중 하나입니다.

{
  "error": {
    "code": "workspace_key_required",
    "message": "This Format belongs to a team workspace. Use an API key created in that workspace.",
    "request_id": "req_…",
    "category": "auth",
    "stage": "auth",
    "retryable": false,
    "retry_after_seconds": null,
    "public_reason": "workspace_key_required",
    "next_action": "authenticate",
    "details": { "workspace_id": "org_…" }
  }
}

Sume API는 어떤 상태 코드를 반환하나요?

생성 시점의 4xx는 아무것도 실행되지 않았고 아무것도 청구되지 않았다는 뜻이므로, 재시도하지 말고 호출을 고치세요. 문서는 403 insufficient_scope를 루프에서 재시도하는 것을 가장 흔하고 가장 비싼 실수로 꼽습니다.

Formats API에는 workspace_key_required, format_not_found 같은 자체 코드가 더 있으며, 오류와 비용 (영문)에 전부 나와 있습니다.

요금제별 Sume API 요청 한도는 얼마인가요?

모든 키에는 워크스페이스 요금제로 정해지는, /v1 전체에 걸친 분당 요청 예산이 있습니다. 읽기와 쓰기는 예산이 따로 있고 읽기는 쓰기 숫자의 마흔 배를 받으므로, 폴링이 생성 요청에 쓸 예산을 잡아먹지 않습니다. 읽기는 영수증, status_url, 목록 조회 같은 모든 GET입니다. 쓰기는 그 밖의 전부로, 실행과 큐 생성, 취소, 재전송이 여기에 해당합니다.

모든 응답에는 그 요청이 쓴 예산 기준의 ratelimit-limit, ratelimit-remaining, ratelimit-reset(윈도가 초기화되기까지 남은 초)이 실립니다. 429에는 초 단위의 retry-after가 추가되고, error.details.scope에 어느 예산인지가 read 또는 write로 표시됩니다. 요청 수를 직접 세지 말고 이 헤더에 맞춰 속도를 조절하세요.

429 queue_full은 요청 한도인가요?

아닙니다. queue_full은 대기 중이거나 처리 중인 기존 Job이 끝나거나 취소될 때까지 Sume가 그 워크스페이스의 유료 생성 Job을 더 받을 수 없다는 뜻입니다. 동시성 한도가 찬 것 자체는 오류가 아닙니다. 큐 용량이 남아 있는 동안 Sume는 유효한 Job을 queued로 수락합니다. 요청 속도를 올려도 요금제의 동시성 한도는 올라가지 않습니다. 접수 과정은 영상 Job 동시성과 큐에서 자세히 다룹니다.

언제, 어떻게 재시도해야 하나요?

429를 받으면 백오프하고, retry-after가 있으면 그 값을 따르세요. 안전하지 않은 제출 요청은 멱등성 키 없이 재시도하지 마세요. 코드별로 보면 다음과 같습니다.

• 폴링 루프 안의 429나 503은 일시적입니다. 루프를 그만둬도 실행이나 그 비용은 멈추지 않으므로, 백오프한 뒤 다시 폴링하세요.
• provider_capacity_exceeded와 503 studio_agent_upstream_unavailable: 같은 멱등성 키로 나중에 재시도하세요.
• provider_not_configured: 공격적으로 재시도하지 말고 카탈로그와 런타임 상태를 확인하세요.
• 409 idempotency_key_in_use는 재시도할 수 있습니다. 1초쯤 기다렸다가 다시 보내세요.
• 402 insufficient_credits: 먼저 충전하세요. 충전하지 않고 재시도하면 같은 응답이 돌아옵니다.
• image_not_fetchable 또는 input_media_unreachable: 입력 미디어가 공개 HTTPS 이미지 URL인지 확인한 뒤 재시도하세요.

실패한 Job이나 실행은 무엇을 알려 주나요?

실패한 Job은 카테고리, 단계, 재시도 가능 여부, retry-after 초, 공개 사유, 다음 동작 같은 공개 오류 메타데이터를 노출합니다. 카테고리에는 validation, auth, quota, queue, generation_unavailable, generation_rejected, generation_timeout, runtime_unavailable, worker_timeout, internal이 있습니다.

Formats API에서 202가 나중에 생성 오류로 바뀌는 일은 없습니다. 실패는 영수증에 status: "failed"로 오며, unattended_blocked, output_schema_unsatisfied, deliverable_missing, format_run_failed 같은 error.code가 함께 오고 primary_output_url은 null입니다. 이 코드 집합은 열려 있다고 보고, 실패한 실행은 새 Idempotency-Key로 재시도하세요.

지원팀에 문의할 때는 request id, 실행 ID나 Job ID, error.code를 알려 주세요. API 키, 서명 시크릿, 서명된 URL, 원본 미디어 URL, 비공개 워크스페이스·사용자 ID는 보내지 마세요.