Errors and limits

Request errors return a non-2xx HTTP status and an error envelope:


{
  "code": 402,
  "error": {
    "message": "Insufficient balance. Please top up your account",
    "type": "PaymentRequired",
    "code": "insufficient_balance"
  }
}

Branch on the HTTP status and error.code, not on the English message.

HTTP	Common code	Action
400	`invalid_input`	Correct the model ID, fields, values, or conditional requirements.
401	`api_key_missing`, `api_key_invalid`	Send a valid API key.
402	`insufficient_balance`	Top up before retrying. No task was created.
404	`task_not_found`, `generation_not_found`	Check the ID and owning account.
429	`unknown_error`	Back off and retry with jitter.
500, 503	`unknown_error`	Retry a limited number of times with exponential backoff.

Failed tasks

A media generation can be accepted and fail later. The status endpoint still returns HTTP 200, but data.status is failed and data.errorMessage contains a sanitized explanation. The charge is refunded automatically.

Do not submit a second paid generation merely because polling is slow. Retry only after the original task is terminal.

Rate limits and retries

A 429 response means the current window is exhausted. Respect retry headers when present and use exponential backoff with random jitter. For task polling, wait 5–10 seconds before the first request and increase the interval up to 30 seconds. Webhooks avoid most status traffic.

Retry 429, connection failures, 500, and 503 with capped backoff.
Do not retry 400, 401, 402, or 404 unchanged.
Reconcile a timed-out create call before submitting another generation.