Sume API 오류 코드 총정리: 표면별 색인과 다음 조치

Sume API 오류 코드는 공통 봉투 하나에 담기는 소문자 error.code 토큰입니다. unauthorized, rate_limited 같은 몇 가지 공통 코드는 API 전체에 적용되고, 나머지는 유료 생성, Format 실행과 패키지, Scheduled 실행, Agent Completions, 미디어 도구, 호스팅 MCP 등 표면별로 문서화되어 있습니다. HTTP 상태로 먼저 분기하고, 그다음 code, 마지막으로 next_action으로 분기하세요.

아래 코드는 오류와 요청 한도 (영문)와 오류와 비용 (영문)을 비롯한 각 표면의 문서 페이지에서 가져왔으며, 2026-09-27에 확인했습니다. 봉투, 일반 코드, 재시도 요령은 Sume API 오류와 요청 한도에서 다룹니다. 이 글은 코드를 표면별로 색인하고, 각 묶음을 설명하는 글을 링크합니다.

표면마다 어떤 오류 코드를 반환하나요?

각 행의 코드는 모두 해당 표면의 문서에 나옵니다. 코드 집합은 열려 있으므로, 처리하는 코드로만 분기하고 나머지는 그대로 통과시키세요.

HTTP 상태 대신 영수증으로 오는 오류는 무엇인가요?

위 표의 세 행은 요청에 대한 4xx나 5xx로 돌아오지 않습니다. 202를 반환한 Format 실행이 나중에 생성 오류로 바뀌는 일은 없으며, 실패는 영수증에 status: "failed"와 error.code로 옵니다. 자식 실행이 끝나면 대량 실행 항목의 error는 format_run_failed나 format_run_canceled 중 하나일 뿐이므로, 사유는 자식 실행에서 읽으세요. 실패한 생성 Job은 카테고리, 단계, 재시도 가능 여부, 다음 동작을 담은 error를 노출합니다.

일부 미디어 도구 코드와 자막 코드도 요청이 아니라 실패한 Job에 담겨 옵니다. 문서는 detach_source_has_no_audio 같은 워커 측 거부를 따로 표시하며, 자막 Job은 caption_no_speech나 두 가지 스크립트 정렬 코드로 실패합니다.

웹훅도 같은 규칙을 따릅니다. 1 MiB를 넘는 실행 영수증은 payload: null과 함께 error.code가 payload_too_large인 상태로 전달되지만, status는 여전히 실행의 실제 결과를 보고합니다.

코드마다 다음에는 무엇을 해야 하나요?

HTTP 오류의 next_action은 authenticate, fix_input, add_funds, retry_later, poll_status, inspect_events, contact_support 중 하나이며, 실패한 자막 Job은 use_overlay_captions나 simplify_script_text_or_omit을 제시할 수도 있습니다. 실제로는 다음과 같이 대응하세요.

• 키를 고치세요. unauthorized, insufficient_scope, workspace_key_required가 여기에 해당합니다. 기존 키에는 스코프를 추가할 수 없으므로 새 키를 발급하세요.
• 요청을 고치세요. invalid_request, unknown_parameter, output_schema_invalid, 그리고 미디어 도구의 거부가 여기에 해당합니다. Format 실행 생성 시점의 4xx는 아무것도 실행되지 않았고 아무것도 청구되지 않았다는 뜻입니다.
• 잔액을 충전하세요. insufficient_credits가 여기에 해당하며, 충전하지 않고 재시도하면 같은 응답이 돌아옵니다.
• 기다렸다가 재시도하세요. rate_limited는 retry-after만큼 기다린 뒤, idempotency_key_in_use는 1초쯤 뒤에, provider_capacity_exceeded는 같은 멱등성 키로 재시도합니다.
• 폴링하거나 레코드를 읽으세요. run_not_completed는 실행이 아직 진행 중이라는 뜻이므로 status_url을 폴링하세요. job_not_completed는 결과가 없는 모든 Job에 돌아오므로, 실패한 Job의 오류는 GET /v1/jobs/{id}에서 읽으세요.

잘못 읽기 쉬운 코드는 무엇인가요?

몇몇 코드는 상태 코드 계열이 암시하는 것과 뜻이 다릅니다.

• 403 insufficient_scope가 404 format_not_found로 오는 일은 없습니다. 유효한 키에 스코프가 빠져 있으면 항상 403을 받습니다.
• 404 format_not_found는 다른 사람의 Format, 그리고 공유 권한이 대기 중이거나 제거된 공유 Format에도 돌아옵니다. 이 404는 다른 테넌트의 존재를 일부러 숨기는 응답입니다.
• 502 attachment_fetch_failed는 입력 문제입니다. next_action이 fix_input이므로 URL을 공개적으로 접근 가능하게 만드세요.
• Scheduled 실행의 503 studio_agent_upstream_unavailable은 retryable: false를 보고하지만, 문서는 횟수를 제한한 재시도는 합리적이라고 설명합니다.
• 알 수 없는 최상위 필드는 Format 실행에서는 400 unknown_parameter이지만, Scheduled 실행에서는 조용히 무시됩니다.
• unsupported_media_type은 대부분의 경로에서 JSON이 아닌 요청 본문(415)을 뜻하지만, 트림, 필터, 오디오 분리에서는 소스 URL에 보낸 HEAD 요청이 영상을 반환하지 않았다는 뜻입니다.