Video Errors & Recovery
Validate before submitting
Section titled “Validate before submitting”Check model access with your API key and retrieve the selected model’s supported parameters. Use only supported media inputs and publicly accessible HTTPS media URLs. A model ID’s name alone does not define its limits.
Distinguish submission from polling
Section titled “Distinguish submission from polling”Submission times out
Section titled “Submission times out”A connection error or lost POST response does not prove that generation was rejected. Do not automatically repeat the POST: a second submission can create another billable task. Check your application’s saved task IDs and account task history; contact support if acceptance cannot be determined.
An application-side unique reference helps your own duplicate prevention, but this guide does not promise server-side deduplication for arbitrary repeated video requests.
Polling times out
Section titled “Polling times out”Retry GET /v1/videos/{task_id} using the same ID. A client polling deadline does not cancel generation, prove failure, or release reserved balance.
Task is still pending
Section titled “Task is still pending”For queued or in_progress, keep polling with a bounded interval and backoff. Do not create another task to resume the existing one.
Task is failed
Section titled “Task is failed”Read error.message and correct the cause before deciding whether to submit again. A new submission is a separate task and may incur a charge. Do not assume that every failure is temporary or that an unchanged request will succeed.
Confirmed failure triggers failure settlement. Check balance and usage records; this is distinct from an uncertain or unknown task that still requires reconciliation.
Task is unknown
Section titled “Task is unknown”Execution could not be confirmed. Stop automatic resubmission, retain the task ID, and contact support. Reserved balance can remain held while the task is reconciled.
Retry policy
Section titled “Retry policy”| Operation | Recommended behavior |
|---|---|
| GET task status | Retry transient connection errors, 429, and 5xx with bounded backoff |
| POST rejected for invalid input or access | Correct the reported cause before making another attempt |
| POST with uncertain acceptance | Reconcile first; do not blindly resubmit |
| New POST after confirmed task failure | Review the error and expected cost before submitting |
Reporting an issue
Section titled “Reporting an issue”Provide the task ID, exact model ID, request time, and redacted error response. Keep API keys, login tokens, and private media credentials out of reports. See Error Handling for more guidance.