Video Errors & Recovery

Common Errors

Authentication Errors

Code	Meaning	Fix
invalid_api_key	Key is missing, wrong, or revoked	Check your key
insufficient_balance	Not enough credit	Top up in Wallet

Request Errors (4xx)

Code	Meaning	Fix
invalid_model	Model name not recognized	Check Available Models
invalid_duration	Duration out of range	Check model’s allowed range
invalid_resolution	Resolution not supported by model	Check model’s supported resolutions
invalid_media	Reference media URL invalid or unreachable	Verify URL is publicly accessible
content_policy	Prompt violates content policy	Rephrase your prompt

Task Failures (returned in polling)

Code	Meaning	What to do
generation_failed	Model failed to generate	Check error message; usually content-related
timeout	Task exceeded time limit	Check if result is still available; don’t resubmit blindly
upstream_error	Upstream service issue	Wait and retry

Timeout vs Failure

These are different situations that need different handling:

Your HTTP connection times out while polling

This does not mean the task failed. The task may still be running.

Action: Just poll again with the same task ID. Don’t resubmit.

# Good: retry polling
try:
    result = poll(task_id, timeout=30)
except requests.Timeout:
    # Connection timed out, but task is still running
    time.sleep(10)
    result = poll(task_id, timeout=30)  # Just try again

Task status changes to failed

The generation actually failed.

Action: Check the error field for the reason. The charge is automatically refunded.

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "Content policy violation"
  }
}

Retry Guidelines

When to retry

Situation	Safe to retry?	Notes
HTTP connection error	✅ Yes	Task may not have been submitted
401/403 authentication	✅ Yes	Fix the key first
429 rate limit	✅ Yes	Wait and retry
Task failed with content policy	⚠️ Only if you change the prompt	Same prompt will fail again
Task failed with upstream error	✅ Yes	Temporary issue
Polling timeout (task still queued/in_progress)	❌ No	Task is still running — resubmitting creates a duplicate charge

When NOT to retry

• Task is still queued or in_progress — be patient, it’s working
• Content policy failure with the same prompt — modify the prompt first
• You’ve already submitted and lost the task ID — check your logs before creating duplicates

Refunds

Automatic refunds

When a task fails, the charge is automatically refunded to your balance:

• The refund typically appears within minutes
• You can verify in Wallet → Transaction History
• The entry will show a refund record linked to the failed task

What’s NOT refunded

• Successful generations where the output doesn’t meet your creative expectations
• Tasks that complete but the video URL expires before you download it
• Duplicate submissions (submitting the same task twice because you didn’t save the first task ID)

Best Practices

1. Save task IDs immediately — store them in your database or queue
2. Use idempotency in your application — tag submissions with a unique reference so you don’t accidentally submit twice
3. Download videos promptly — URLs may expire; don’t assume permanent availability
4. Monitor your balance — set up alerts for low balance in the dashboard
5. Log error responses — the error.message field contains actionable information