Skip to main content
A v1 HTTP error includes code, message, and request_id. Use the HTTP status for control flow and keep the request ID for support. Account errors can also include cta and next_action; show the described account action when cta is true.

​
Retry a creation safely

All seven v1 creation endpoints accept an optional Idempotency-Key header containing 1–128 visible ASCII characters. Use a unique value for each intended creation and persist it with the exact request body before sending. Repeat the same method, path, and JSON body with the same key after a network failure. A finalized response is replayed for 24 hours after completion, including its original job IDs and HTTP status. A replay is marked with Idempotency-Replayed: true. Keys are scoped to the authenticated user and resolved workspace.
  • idempotency_conflict: that key was used for a different request. Correct the retry; use a new key only when you intend new work.
  • request_in_progress: the original request is running or its outcome is uncertain. Retry the same key later. If it persists, contact support; do not replace the key to bypass it.
An unfinished or uncertain request is never automatically rerun, even after 24 hours. This prevents a crashed request from charging twice. After a finalized receipt’s 24-hour replay window, reuse of its key may create new work. Do not use this window as long-term storage for your job IDs. Uploads and asset changes do not use creation idempotency keys. The legacy endpoints retain their previous retry behaviour. If you omit a key and lose a creation response, check Studio before submitting again.

​
Processing failures

An accepted job may later finish with failed or policy_blocked. Its result is null and error contains code and message. Stop polling. Change blocked or invalid inputs before creating a new request; preserve the failed job ID for troubleshooting. A polling deadline does not cancel the job. Retry temporary read failures with bounded backoff and retain accepted IDs so polling can resume. For support, send the request ID, job ID if available, endpoint, status, and approximate UTC time to [email protected]. Redact API keys and Authorization headers.