Handle Imagine video generation errors

SDK generate() / extend() raise VideoGenerationError from xai_sdk.video when the job fails after create. Manual polling returns status: "failed" with an error object. Auth, missing model, and rate-limit problems come back synchronously before a request_id exists — they never appear inside that deferred error.code.

SDK try / except

import os
import xai_sdk
from xai_sdk.video import VideoGenerationError

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

try:
    response = client.video.generate(
        prompt="A cat lounging in a sunbeam, tail gently swishing",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(response.url)
except VideoGenerationError as e:
    print(f"Generation failed [{e.code}]: {e.message}")
except TimeoutError:
    print("Timed out — raise timeout or simplify the prompt")

VideoGenerationError carries code (str) and message (str). Pair it with TimeoutError when you customized poll wait via Customize Imagine video SDK poll timeout.

Failed poll body (REST / manual)

{
  "status": "failed",
  "error": {
    "code": "invalid_argument",
    "message": "Prompt cannot be empty. Please provide a prompt."
  }
}

error.code	Meaning	Next step
invalid_argument	Bad duration, media, prompt length, conflicting modes, or moderation block	Fix inputs; submit a new request
permission_denied	Key/team lacks the video capability	Check team access and key scope
failed_precondition	Mode/resolution not available on the selected model (e.g. 1080p on classic, edit/extend limits)	Change model, mode, or resolution
service_unavailable	Temporary overload	Retry later
internal_error	Service failure	Retry; if it persists, contact xAI with the request_id

Status values while polling

Status	Meaning
pending	Still generating
done	Ready — read video.url
expired	Request expired
failed	See error above

Pitfalls

• Do not treat a sync 401/429 as a deferred failure — there is no request_id to poll.
• respect_moderation on a successful response can still be false; check it before publishing the URL.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.