2026-09-26포맷

Sume Format 실행 실패: 오류 코드, 세부 정보, 대응 방법

실패한 Sume Format 실행은 error.code에 원인을 담습니다. 코드별 details 필드, 청구되는 비용, 이어 갈지 재시도할지를 정리했습니다.

읽는 시간 6분Sume

Sume Format 실행이 실패하면 영수증은 status: "failed", 원인을 알려 주는 error.code, 그리고 대개 details에 더 자세한 내용을 담은 output_error와 함께 돌아옵니다. 다음 단계는 코드에 따라 정해집니다. 입력이나 스키마를 고치거나, previous_run_id로 실행을 이어 가 이미 만든 클립을 살리거나, 새 Idempotency-Key로 재시도합니다.

아래의 코드와 조언은 2026-09-26에 확인한 Sume 문서 오류와 비용 (영문)과 구조화 출력 (영문) 페이지에서 가져왔습니다. 오류 봉투와 생성 호출이 돌려줄 수 있는 4xx 코드는 Sume API 오류와 요청 한도를 참고하세요.

실패한 실행의 영수증에는 무엇이 담기나요?

202가 나중에 생성 오류로 바뀌는 일은 없습니다. 영수증을 받은 뒤의 실패는 그 영수증에 담겨 옵니다. 실패한 영수증에는 다음이 들어 있습니다.

종료된 모든 실행처럼 status: "failed"와 next_action: "none"이 있습니다.
error: { code, message }가 있습니다. 분기는 code로 하고, message는 매칭하지 말고 로그에 남기세요.
대부분의 경우 output_error: { code, message, details }가 있습니다. 아래 표에 나오는 필드는 대부분 이 details에 들어 있습니다.
실행이 생성한 모든 것을 담은 artifacts[], 그리고 스키마를 충족한 부분 결과를 그대로 담은 output이 있습니다.
항상 primary_output_url: null입니다. 그래서 if (run.primary_output_url)은 “the deliverable exists”(완성본이 있음)를 확인하는 안전한 검사로 남습니다.

{
  "data": {
    "status": "failed",
    "output": null,
    "output_error": { "code": "unattended_blocked", "message": "no avatar matched the brief, so no video was made." },
    "error": { "code": "unattended_blocked", "message": "no avatar matched the brief, so no video was made." }
  }
}

실행은 어떤 실패 코드를 보고할 수 있나요?

이 집합은 열려 있다고 보세요. 새 코드가 추가될 수 있으므로, 모든 코드를 빠짐없이 분기하려 하지 말고 아는 코드만 처리한 뒤 나머지는 그대로 통과시키세요.

실행 중 실패 코드, 오류와 비용 (영문)과 구조화 출력 (영문) 기준, 2026-09-26 확인.
`error.code`	발생한 일	읽을 필드	다음 단계
`unattended_blocked`	사람 없이는 넘을 수 없는 게이트에 걸림. 브리프에 맞는 아바타가 없거나, 채팅이었다면 물어봤을 입력이 빠진 경우. `message`는 그대로 보여 줄 수 있게 작성됨	`harvested`, 그리고 `assembled_deliverable: false`	입력이나 브리프를 고친 뒤 새 키로 재시도
`output_schema_unsatisfied`	결과가 `output_schema`와 맞지 않거나, 실행이 만들지 않은 미디어를 참조함	`rejected_urls[]`(앞 10개만) 또는 `violations[]`, 그리고 `harvested`	`harvested`를 스키마가 요구하는 것과 비교. 필드를 nullable로 완화하거나 지시문 변경
`deliverable_missing`	Format이 `io.output_kind`에 미디어를 선언했는데 실행이 하나도 만들지 않음	`declared_output_kind`, 그리고 `harvested`	재시도. 반복되면 입력이 레시피가 기대하는 것과 다름
`primary_output_missing`	결과는 스키마를 충족했지만 지정한 `primary_output_key`가 비어 있음	`primary_output_key`. 부분 결과는 `output`에 있음	실행을 이어 가서 빈 곳을 채우거나 재시도
`agent_reported_failure`	실행 스스로 결과를 전달하지 못했다고 보고함. 명시적 실패, `failed`나 `stand-in`인 미디어 슬롯, 또는 미디어 유형이 맞지 않는 primary 출력	`reason`(`explicit_failed`, `slots_failed`, `primary_not_deliverable`), 그리고 `non_delivered_slots[]` 또는 `primary_media_type`	실행을 이어 가거나 새 키로 다시 실행. 클립은 실제 결과임
`incomplete_assembly`	생성 Job이 아직 끝나지 않은 채 실행이 시간 한도에 도달함	`pending_job_count`, `pending_jobs[]`	`previous_run_id`로 실행 이어 가기
`output_extraction_failed`	`reason: harvest_threw`이면 실행이 끝난 뒤 호스트 자체의 harvest 단계가 크래시함	`reason`, `thrown`	호스트 결함. 실행 ID를 알려 주기
`mcp_unavailable`	실행에 필요한 Sume MCP 도구가 붙지 않아, 모델이 실행되기 전에 실패함	`retryable: true`, `charged: false`	새 키로 재시도
`provider_unavailable`	모델 제공자 스트림이 끊겼고, 완성본이 나오기 전에 재연결 횟수를 다 씀	`retryable: true`	새 키로 재시도
`format_run_failed`	일반 실패. 상한을 넘어 쓰려던 실행도 여기로 옴	`message`, 그리고 `usage`	`usage.billable_amount_usd_micros`와 `usage.generation_spend_cap_usd_micros` 비교

스키마가 맞지 않으면 실행이 실패하나요?

API에서는 그렇습니다. API를 통한 실행은 무인 실행이므로 projection 실패가 곧 실행 실패입니다. status는 failed가 되고, error에는 output_error와 같은 이유가 담깁니다. 사람이 스레드를 읽는 에이전트 UI에서는 같은 형태가 초안으로 completed 상태에 남습니다.

completed로 남는 경우가 하나 있습니다. reason: harvest_unavailable인 output_extraction_failed로, 실행이 마무리되는 동안 미디어를 읽지 못한 경우입니다. 영수증은 다음 읽기에서 채워지며, 채워지지 않으면 새 키로 재시도하세요. 실패한 실행에서도 장면을 읽을 수 있게 하려면 실패한 AI 영상 실행의 부분 결과를 참고하세요.

실패한 실행은 재시도해야 하나요, 이어 가야 하나요?

위의 코드별 조언은 문서의 세 가지 규칙을 따릅니다.

새 Idempotency-Key로 재시도하세요. 이전 키는 이미 받은 영수증에 묶여 있어서, 다시 쓰면 같은 실패 영수증이 돌아옵니다.
incomplete_assembly처럼 실패가 클립을 남겼다면 재시도 대신 이어 가세요. 끝난 클립은 스레드에 있으며 다시 생성되지 않습니다. 호출 방법은 AI 영상의 장면 하나를 다시 생성하기에 있습니다.
원인이 여러분 쪽에 있으면 먼저 고치세요. unattended_blocked라면 브리프를, output_schema_unsatisfied라면 대개 Format이 만들지 않는 파일을 요구하는 스키마를 고쳐야 합니다.

실패한 실행도 과금되나요?

실패 전에 끝난 생성은 청구되며, 뒤 단계가 실패해도 환불되지 않습니다. mcp_unavailable은 생성이 실행되기 전에 실패하므로 details.charged는 false이고, 청구된 것도 없습니다.

지출은 영수증에서 읽으세요. usage.billable_amount_usd_micros는 상한에 대해 집계되는 생성 지출이고, usage.debited_usd_micros는 에이전트 자체의 LLM 턴을 포함해 지갑에서 실제로 차감된 금액입니다. 상한을 넘어 쓰려던 실행은 format_run_failed와 함께 failed로 끝나며, usage가 상한에 얼마나 가까웠는지 보여 줍니다.

실패한 실행은 웹훅으로 어떻게 도착하나요?

같은 실행이 status: "ERROR", outcome: "error", 그리고 payload.error.code를 그대로 비추는 error.code와 함께 도착합니다. payload는 GET /v1/format-runs/{run_id}의 data와 바이트 단위로 같으므로, 핸들러 하나가 웹훅과 폴링 모두에서 같은 코드로 분기할 수 있습니다. payload는 영수증이 1 MiB를 넘을 때만 null이며, 그때는 error.result_url이 가져올 위치를 알려 줍니다. 취소되거나 건너뛴 실행은 웹훅을 전혀 보내지 않습니다.

출처

작성자 Sume