2026-09-26개발자

AI 영상 생성 Job은 왜 실패했나요? Job 오류 읽는 법

실패한 Sume Job에는 category, stage, retryable, public_reason, next_action이 담긴 공개 오류가 있습니다. 읽는 곳과 필드별로 할 일을 설명합니다.

읽는 시간 5분Sume

Sume 영상 생성 Job이 failed로 끝나면 GET /v1/jobs/{id}의 Job 레코드에서 공개 error 객체를 읽으세요. category와 stage는 무엇이 어디서 잘못됐는지를, retryable과 retry_after_seconds는 같은 요청을 나중에 재시도하면 도움이 될지와 그 시점을, next_action은 fix_input이나 retry_later처럼 다음에 할 일을 알려 줍니다.

아래 필드는 Sume 문서 오류와 요청 한도 (영문), Job과 결과 (영문), 그리고 라이브 OpenAPI 레퍼런스에서 가져왔으며, 모두 2026-09-26에 확인했습니다. 이 글은 접수된 뒤 나중에 실패한 Job을 다룹니다. 제출 시점에 돌아오는 오류는 Sume API 오류와 요청 한도에 있습니다.

오류는 어디서 찾나요?

/result에는 없습니다. GET /v1/jobs/{id}/result는 완료된 Job 전용이며, 그 밖의 경우에는 409 job_not_completed로 응답합니다. 실패 내용은 Job 레코드에서 읽으세요.

GET /v1/jobs/{id}는 error가 담긴 Job을 반환합니다. TypeScript에서는 waitForJob이 이 레코드로 resolve하므로, 여기서 status, result, error를 읽으세요.
실패하거나 취소된 Job에서는 상태 페이로드의 next_action이 inspect_events로 바뀝니다. GET /v1/jobs/{id}/events에서는 종료 이벤트와 생성 실패 이벤트에 같은 형태의 error가 들어 있을 수 있습니다.
job.failed 웹훅은 status: "ERROR"를 쓰고 error 객체를 포함합니다.
POST /v1/videos에서는 폴링 응답의 error가 단순한 실패 메시지입니다. 같은 Job을 GET /v1/jobs/{id}/status에서 Sume 형태로 계속 읽을 수 있습니다.
Jobs 대시보드는 공개 결과나 오류 데이터와, 가능한 경우 타임라인 정보를 보여 줍니다.

Job 오류 객체에는 무엇이 들어 있나요?

이 오류는 공개해도 안전합니다. 원본 생성 task ID, 생성 서비스 URL, 서명된 URL, 요청 본문, 스택 트레이스, 시크릿은 빠져 있습니다. 표 다음에 OpenAPI 예시가 있습니다.

오류와 요청 한도 (영문)와 OpenAPI 레퍼런스 기준 Job 오류 필드, 2026-09-26 확인.
필드	알려 주는 것
`category`	실패의 종류. 다음 단계와 대응됨. 다음 표 참고
`stage`	실패한 지점. `validation`, `queue`, `usage_reservation`, `generation_submit`, `generation_processing`, `video_caption_render`, `video_caption_source`, `audio_processing`, `usage_settlement`, `webhook_delivery`, `cancellation`, `internal` 중 하나
`retryable`, `retry_after_seconds`	같은 요청을 나중에 재시도하면 도움이 될지 여부, 그리고 일시적 실패에 대한 재시도 힌트(Sume에 정해진 지연 시간이 없으면 null)
`public_reason`	`generation_rejected`, `image_content_rejected`, `content_policy_rejected`처럼 기계가 다루기 쉽고 그룹화 기준으로 써도 안전한 사유
`next_action`	`fix_input`, `simplify_script_text_or_omit`, `add_funds`, `retry_later`, `poll_status`, `inspect_events`, `contact_support`, `use_overlay_captions` 중 하나
`code`, `message`	호환성을 위해 유지하는 안정적인 코드와, 공개해도 안전한 메시지. 프로바이더 생성 실패에서는 저장된 업스트림 사유가 있으면 정제한 그 사유가 `message`
`details`	선택 사항. 프로바이더 실패에는 `provider_error_type`, `provider_error_message`, `input_field`가 추가될 수 있으며, 키나 URL은 절대 담기지 않음

{
  "code": "generation_failed",
  "message": "Generation failed.",
  "category": "generation_rejected",
  "stage": "generation_processing",
  "retryable": false,
  "retry_after_seconds": null,
  "public_reason": "generation_rejected",
  "next_action": "inspect_events"
}

카테고리별로 무엇을 해야 하나요?

먼저 category로 분기하세요. 문서는 다음 카테고리와 각각의 일반적인 다음 동작을 나열합니다.

오류와 요청 한도 (영문) 기준 Job 오류 카테고리, 2026-09-26 확인.
카테고리	일반적인 다음 동작
`validation`	입력 수정
`auth`	API 키와 워크스페이스 접근 권한 확인
`quota`	잔액 충전 또는 요청 비용 낮추기
`queue`	같은 멱등성 키로 나중에 재시도
`generation_unavailable`	나중에 재시도
`generation_rejected`	이벤트 확인 후 지원되지 않는 입력 수정
`generation_timeout`	상태 폴링 또는 나중에 재시도
`runtime_unavailable`	나중에 재시도. 공격적인 재시도는 금지
`worker_timeout`	상태 폴링 또는 나중에 재시도
`internal`	이벤트 확인 후 request ID나 Job ID와 함께 지원팀에 문의

영상 생성이 왜 거부됐나요?

generation_rejected Job은 다시 보낼 것이 아니라 입력을 바꿔야 합니다. 먼저 message를 보세요. Sume가 저장해 둔 것이 있으면 정제된 업스트림 검증 상세나 거부 메시지가 여기에 담깁니다. details.input_field는 image_url이나 duration처럼 프로바이더가 문제로 지목한 요청 필드를 알려 주고, details.provider_error_type은 file_download_error나 value_error 같은 유형을 알려 줍니다.

POST /v1/videos에 대한 문서의 체크리스트는 이렇습니다. 프롬프트는 적절하게, 모델 가이드라인 안에서 작성하고, 레퍼런스 이미지가 있다면 공개 HTTPS로 접근할 수 있고 지원되는 형식인지 확인하세요. 자막 Job에는 use_overlay_captions와 simplify_script_text_or_omit이라는 별도의 다음 동작이 있습니다. 영상에 자막을 입히는 방법을 참고하세요.

실패한 Job은 재시도해야 하나요? 지원팀에는 무엇을 알려야 하나요?

retryable에 따라 결정하세요. true이면 retry_after_seconds가 있을 때 그만큼 기다리세요. runtime_unavailable이라면 나중에 재시도하되 공격적으로 재시도하지는 마세요. false이면 같은 요청을 재시도해도 도움이 되지 않을 것으로 보므로, 대신 next_action을 따르세요. 입력을 고치거나, 잔액을 충전하거나, 지원팀에 문의하면 됩니다. 실패한 Job은 해당하는 경우 예약을 해제하거나 환불합니다. 과금은 실패한 AI 영상 Job에도 비용이 드나요?에서 다룹니다.

internal 실패라면 이벤트를 확인한 뒤 request ID와 Job ID를 담아 지원팀에 문의하세요. 보고에서 빼야 할 정보는 Sume API 오류와 요청 한도에, 어떤 ID가 무엇인지는 request ID, Job ID, 실행 ID에 정리돼 있습니다.

출처

작성자 Sume