Async video jobs: polling, timeouts and retries
Updated 2026-10-02
Video generation does not fit a request/response cycle, so a video API gives you a job. A robust client treats the job as the unit of work.
States
queued → in_progress → completed | failed. Treat anything else as unknown and keep polling.
Polling
Poll every 4–6 seconds with a hard deadline (10 minutes is a sensible ceiling for most models). Polling is free, so there is no reason to hold a connection open or poll more aggressively.
Retries
| Status | Meaning | Do this |
|---|---|---|
| 429 | Rate limited | Sleep for Retry-After, retry creation |
| 402 | Out of credit / cap hit | Don't retry; top up |
| 400 | Bad model id or params | Don't retry; fix the request |
| 5xx | All upstream hosts failed | Retry with backoff; not billed |
Idempotency of cost
Creation is billed once, in full, from the requested duration. A job that ends failed because every upstream host failed is not billed. Don't re-create a job just because polling is slow — you would pay twice.
See the quickstart for a full working client.
VideoRouter puts it next to dozens of other video and image models behind one API key, so you can compare providers, prices and fail over automatically. Compare providers on VideoRouter →