Failures and retries

A video goes through many steps, and each one calls outside providers for images, clips and speech. When a step fails, Scenema tries it again on its own. When a provider is down, the video waits for it. Only when that does not work does the video fail, and most failures can then be retried without losing what was already made.

When a provider is down

If a step keeps failing because a provider is down (it times out, is overloaded, or answers with a server error), the video does not fail. It stays processing with the stage waiting, and waiting says since when and why:

{
  "status": "processing",
  "stage": "waiting",
  "waiting": { "since": "2026-10-30T09:12:44.000Z", "reason": "503 Service Unavailable" }
}

Scenema tries the step again every few minutes, and the video carries on by itself once the provider answers. The time spent waiting does not count against the video’s 3 hour limit. After 6 hours of waiting, the video fails with PROVIDER_OUTAGE, which can be retried later.

No webhook is sent while a video waits. The video’s video.completed or video.failed arrives when it ends, as usual.

When a video fails

A failed video reads "status": "failed", with error saying what happened, errorCode naming it, and retryable saying whether a retry can fix it.

`errorCode`	What happened	`retryable`
`PROVIDER_FAILED`	A step failed again and again, on the provider’s side.	yes
`PROVIDER_OUTAGE`	A provider was down for 6 hours.	yes
`EXPORT_FAILED`	The video could not be exported.	yes
`DEADLINE_EXCEEDED`	The video did not finish within 3 hours.	yes
`INSUFFICIENT_CREDITS`	A step could not be paid for. Top up the workspace, then retry.	yes
`TRANSCRIPTION_FAILED`	The audio could not be transcribed.	yes
`SOUNDTRACK_FAILED`	The soundtrack could not be analyzed.	yes
`START_FAILED`	The video did not start.	yes
`CONTENT_REFUSED`	A provider refused the content. Change the audio or prompt and make a new video.	no
`ACCOUNT_BLOCKED`	The account cannot make videos.	no
`PIPELINE_HELD`	Scenema held the video back: a step failed or started too often, or the team paused it. Contact support.	no

A failed video charges only what the providers already did for it; the rest of its price goes back to the balance.

Retry a failed video

curl -X POST "https://api.scenema.ai/v1/videos/proj_7c2e91a04b6d3f8/retry" \
  -H "Authorization: Bearer $SCENEMA_API_KEY" \
  -H "Idempotency-Key: retry-7c2e-1"

The answer is the video, back in processing, with attempt one higher. The video picks up where it stopped: its storyboard, designs, images and clips are all kept, and only what is missing is made. It gets a fresh 3 hour limit. When it ends, video.completed or video.failed arrives again for this attempt.

A video can be retried up to 3 times, within 7 days of its failure. Send an Idempotency-Key to retry safely: the same key answers the same retry and starts nothing more.

What a retry costs

A video never costs more than one video, however many tries it takes. A retry holds what is left of the video’s price: the price minus what the failed attempts were charged. When the retry completes, the video has cost exactly its price. credits on the video adds up every attempt.

When the workspace cannot hold what is left, the retry answers 402 INSUFFICIENT_CREDITS and the video stays failed.

A new aspect ratio that fails leaves the video completed in the ratio it had; the ratio reads failed in formats. POST /v1/videos/{id}/retry, or a PATCH to that ratio again followed by POST /v1/videos/{id}/generate, retries it the same way: it reuses every keyframe and clip already made for that ratio and holds what is left of the new ratio’s price, so the new ratio never costs more than once.

When a retry is refused

Status	Code	When
409	`VIDEO_NOT_FAILED`	The video is still being made, or has completed.
409	`VIDEO_NOT_RETRYABLE`	The failure cannot be fixed by a retry (`retryable` is false). Make a new video.
409	`RETRY_LIMIT_REACHED`	The video was retried 3 times. Make a new video.
409	`RETRY_WINDOW_PASSED`	The video failed more than 7 days ago. Make a new video.
402	`INSUFFICIENT_CREDITS`	The workspace cannot hold what is left of the price.