2026-09-26Developers

Why did my AI video generation job fail? Reading the job error

A failed Sume job carries a public error: category, stage, retryable, public_reason, and next_action. Where to read it, and what each field tells you to do.

5 min readSume

All posts

When a Sume video generation job ends failed, read the public error object on the job record at GET /v1/jobs/{id}: category and stage say what broke and where, retryable and retry_after_seconds say whether retrying the same request later is expected to help and when, and next_action says what to do next, such as fix_input or retry_later.

The fields below come from Sume's Errors and rate limits and Jobs and results docs and the live OpenAPI reference, read on 2026-09-26. This post covers a job that was accepted and failed later; errors returned at submit time are in Sume API errors and rate limits.

Where do I find the error?

Not on /result: GET /v1/jobs/{id}/result is only for completed jobs and answers 409 job_not_completed otherwise. Read the failure off the job record instead.

GET /v1/jobs/{id} returns the job with its error. In TypeScript, waitForJob resolves with this record, so read status, result, and error off it.
The status payload's next_action turns to inspect_events for failed and canceled jobs. In GET /v1/jobs/{id}/events, terminal and generation-failure events may include an error of the same shape.
A job.failed webhook uses status: "ERROR" and includes an error object.
On POST /v1/videos, the poll response's error is a plain failure message; the same job stays readable in Sume's shape at GET /v1/jobs/{id}/status.
The Jobs dashboard shows public result or error data and timeline information where available.

What is in the job error object?

The error is public-safe: raw generation task ids, generation service URLs, signed URLs, request bodies, stack traces, and secrets are omitted. The OpenAPI example follows the table.

Job error fields, from Errors and rate limits and the OpenAPI reference, read 2026-09-26.
Field	What it tells you
`category`	The kind of failure. It maps to a next step; see the next table.
`stage`	Where it broke: `validation`, `queue`, `usage_reservation`, `generation_submit`, `generation_processing`, `video_caption_render`, `video_caption_source`, `audio_processing`, `usage_settlement`, `webhook_delivery`, `cancellation`, or `internal`.
`retryable`, `retry_after_seconds`	Whether retrying the same request later is expected to help, and a retry hint for transient failures (null when Sume has no specific delay).
`public_reason`	A machine-friendly reason that is safe to group on, such as `generation_rejected`, `image_content_rejected`, or `content_policy_rejected`.
`next_action`	`fix_input`, `simplify_script_text_or_omit`, `add_funds`, `retry_later`, `poll_status`, `inspect_events`, `contact_support`, or `use_overlay_captions`.
`code`, `message`	A stable code kept for compatibility, and a public-safe message. For provider generation failures, `message` is the sanitized upstream reason when one was stored.
`details`	Optional. Provider failures may add `provider_error_type`, `provider_error_message`, and `input_field`, never keys or URLs.

{
  "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"
}

What should I do for each category?

Branch on category first. The docs list these categories with a typical next action:

Job error categories, from Errors and rate limits, read 2026-09-26.
Category	Typical next action
`validation`	Fix input.
`auth`	Check API key and workspace access.
`quota`	Add funds or lower request cost.
`queue`	Retry later with the same idempotency key.
`generation_unavailable`	Retry later.
`generation_rejected`	Inspect events and fix unsupported input.
`generation_timeout`	Poll status or retry later.
`runtime_unavailable`	Retry later; do not retry aggressively.
`worker_timeout`	Poll status or retry later.
`internal`	Inspect events and contact support with the request or job id.

Why was my video generation rejected?

A generation_rejected job needs a changed input, not a resend. Start with message, which carries the sanitized upstream validation detail or reject message when Sume stored one. details.input_field names the request field the provider blamed, such as image_url or duration, and details.provider_error_type gives a type such as file_download_error or value_error.

For POST /v1/videos, the docs' checklist is: keep the prompt appropriate and within model guidelines, and make sure any reference images are reachable over public HTTPS and in supported formats. Caption jobs have their own next actions, use_overlay_captions and simplify_script_text_or_omit; see how to burn captions onto a video.

Should I retry a failed job, and what do I tell support?

Let retryable decide. When it is true, wait retry_after_seconds if present; for runtime_unavailable, retry later but not aggressively. When it is false, retrying the same request is not expected to help, so follow next_action instead: fix the input, add funds, or contact support. Failed jobs release or refund their reservation where applicable; do failed AI video jobs cost money? covers billing.

For an internal failure, inspect events, then contact support with the request id and the job id. Sume API errors and rate limits lists what to leave out of a report, and request id, job id, and run id explains which id is which.

Sources

Written by Sume