Run Lifecycle & Errors
Run statuses, how to poll, and every error your integration should handle.
Run statuses
A run returned by Get Run (or delivered to your webhook) moves through:
| Status | Meaning |
|---|---|
not-started | Accepted, not yet scheduled |
queued | Waiting for a GPU (e.g. at your plan's concurrency limit) |
started | GPU assigned, machine starting (cold start happens here) |
running | Workflow executing — progress (0–1) and live_status update |
uploading | Generation done, outputs uploading |
success | Terminal — outputs are in outputs[] |
failed | Terminal — workflow errored; run logs have details |
timeout | Terminal — exceeded the machine's Workflow timeout |
cancelled | Terminal — cancelled via API or dashboard |
Terminal states never change afterwards. Billing posts at the terminal state, for the time actually used — see How Billing Works.
Polling vs webhooks
Prefer webhooks — pass webhook when queueing and receive status pushes, including the terminal one with outputs. If you must poll getRun, every 3–5 seconds is plenty; use the progress field for UX.
Queue time is unbilled and depends on your plan's Concurrent GPUs limit — runs beyond it wait in queued rather than failing.
Errors to handle
| HTTP | Meaning | What to do |
|---|---|---|
401 | Missing/invalid API key | Check the Bearer header; the key may be revoked |
402 | Billing: no credits, or plan required | Top up / subscribe — see zero-balance behavior. Surface this clearly to end-users |
404 | Unknown deployment/run id | Verify the id and that it belongs to the same workspace as the key |
422 | Invalid request body | The response detail lists the offending fields |
5xx | Transient platform error | Retry with backoff; queueing is safe to retry |
A run that reaches failed or timeout is not an HTTP error — the API call succeeded; check the run's logs for the workflow-level cause.
Sync and streaming variants
The SDK also offers run.deployment.sync (blocks until terminal, returns outputs) and run.deployment.stream (server-sent events with live progress). For production we recommend queue + webhook — sync/stream hold a connection for the whole generation, which video-length jobs will outlive.