Errors & retries
Handle errors, rate limits, retries, and idempotent requests safely.
Send a unique Idempotency-Key of 1–128 visible ASCII characters for every intended video mutation. Persist it before submitting. If a connection fails, repeat the same operation with the same key and identical body. Using a new key means a new operation and can create another paid video.
Reusing a key with a different body is a conflict. Keep operation keys separate: creating a video and requesting its render are two different operations.
| Response | What to do |
|---|---|
400 / 422 | Fix the request fields. Unknown fields are rejected. |
401 | Check that your API key is present, valid, and not revoked. |
402 | Check your workspace’s available credit balance. |
403 | Check the key’s scopes and workspace access. |
404 | Check the resource ID, workspace, and test/live mode. |
409 | Check the current video state or idempotency conflict. |
429 | Honor Retry-After and retry with backoff. |
5xx / network timeout | Retry cautiously with exponential backoff and the same idempotency key. |
Error responses contain error.code, error.message, and request_id. The X-Request-Id response header identifies the request as well. Keep it with your own job logs so support can trace an error. Never log API keys or signed download URLs. Rate and concurrency limits apply to the workspace; use a queue instead of sending an unbounded batch.