Errors & safe retries

Handle API errors, rate limits, idempotency and processing costs without duplicate submissions.

Error format

Errors use application/problem+json. Branch on the HTTP status, not the text of detail. Schema errors may additionally include an errors array describing invalid fields. An illustrative error body:

{"status": 401, "detail": "Provide a valid API key."}

Status	What to do
`400`	Fix malformed JSON or invalid task/media settings
`401`	Check the key, site, expiry and revocation
`402`	Check credits or account restrictions in the workspace
`403`	Use a key with the required scope
`404`	Check the ID; missing and other users’ resources are not exposed
`409`	Inspect the quote, idempotency key or task state; do not blindly resubmit
`410`	Output was deleted, or the original idempotent task was cleaned up
`413`	Reduce the upload/request size
`422`	Fix fields against the endpoint schema
`429`	Wait for `Retry-After` and reduce concurrency
`500` / `502` / `503` / `504`	Back off with jitter; preserve a submission’s key and body

Retry the same logical task

Persist the Idempotency-Key and request body before the first POST /tasks. If the connection times out or the server response is lost, send the same key and body again. Within one account, the same request returns the original task even after rotating API keys. Different parameters with the same key return 409. JSON formatting and property order do not matter.

An expired quote may still belong to a submission that succeeded but whose response was lost: retry the original key/body first to recover that task. Refresh a quote and use a new key only after confirming that you are creating a new logical task. After a task is cleaned up, its key remains reserved and replay returns 410.

Never retry all errors automatically. For retriable failures use bounded exponential backoff with jitter; honor Retry-After when present. A client timeout does not cancel a server task. Do not log API keys or signed URLs.

Rate limits and polling

Each key allows 120 requests per minute. Twenty invalid key attempts from one IP within a minute trigger a temporary block. Multiple keys do not raise your account’s processing concurrency, upload allowance or balance. Polling every two seconds is about 30 requests per minute per active task, so many concurrent tasks need a shared rate budget and a longer interval.

Charges and result retention

A quote does not reserve credits or compute. A valid quoteId locks its quoted price until expiry; maxCostCredits can impose a charge ceiling. Task creation and precharge are atomic. Failed/canceled tasks follow the existing refund rules; canceling a completed successful task does not refund it.

Refreshing signed result links is free. A deleted output cannot be restored by refreshing its URL. Fetching arbitrary remote source URLs and webhook delivery are not supported in this API; upload files first and poll tasks for completion.