"message": "Not enough credits to start this task.",
"details": {}
}
}
Every response — error or success — carries X-Request-Id in the headers. Always
include this in support tickets; it’s the single fastest way for us to trace the
problem.
An HTTP error describes the request outcome; it does not by itself prove
that no task or charge exists. A synchronous operation can fail or time out
after a task was created.
Situation
Meaning
Recovery
Validation/authentication/budget rejection confirmed before creation
No new task was accepted
Correct the stated issue, then retry
Error contains taskId or pollUrl
A task exists; its settled state determines the final charge
Query that task
HTTP 5xx, connection lost, or local timeout with no receipt
Submission outcome may be unknown
Replay the original route/body with the saved idempotency key
Polled task is FAILED or CANCELLED
The task is terminal
Inspect refunded, creditsCharged and retryable before starting a new attempt
A missing task ID in the client is not evidence that submission failed. See
Idempotency and recovery.
This is the curated, human-readable view of the platform error codes.
Module-specific codes, such as the MV_* family for the Music Video API, are
documented in their module guide rather than repeated here. For request and
response schemas, see the Interactive API Reference.
Include x-api-key; confirm the value is active and unexpired, or rotate it.
FORBIDDEN
403
Inspect details.requiredScope / details.clientIp for key restrictions. Paid creation can also be blocked by a billing hold; check billingStatus and resolve payment review or debt before retrying.
Add credits from the dashboard. For MV, Vidu, Subtitles, or Audio Editing, increase maxCredits only when the error details show that your submitted budget cap was exceeded. Suno and Producer do not accept maxCredits.
BALANCE_NOT_INITIALIZED
402
Account balance is not ready yet. Open the dashboard once, then retry.
CREDIT_DEDUCTION_FAILED
500
Recover the original request with the same idempotency key; check any returned taskId before a new attempt.
Confirm the task id and that the task is still available.
TASK_ALREADY_EXISTS
409
Idempotency collision (rare). Re-poll the original id.
CONFLICT
409
Generic state/idempotency conflict (e.g. competing edit). Re-poll or reconcile, then retry.
TASK_CREATION_FAILED
500
Recover with the original idempotency key and body; poll a returned taskId.
TASK_EXECUTION_FAILED
500 / (task status)
Generation failed after the task was accepted. Inspect errorMessage; eligible credits are refunded unless partial output was billable.
EXPIRED
task status
The feature-specific task deadline passed after a final status read. Inspect retryable and refunded, then submit a fresh task when retryable.
PROVIDER_PROCESSING_TIMEOUT
task status
An accepted generation operation remained non-terminal through its processing deadline. Inspect retryable and refunded, then submit a fresh task when retryable.
TASK_CANCELLED
409 / (task status)
Cancelled before completion. Contact support if unexpected.
CONTENT_POLICY_REJECTED can appear as HTTP 422 before a new task is
accepted, or on a terminal FAILED task. It has retryable: false.
Read error.details on an HTTP error and the task’s public failure fields when polling:
Field
Meaning
errorReason / reason
copyright_similarity, audio_recording_match, artist_reference, content_policy, or unknown
actionRequired
modify_lyrics, replace_audio, remove_artist_reference, or modify_input
rejectedField
The input to change: lyrics, audio, prompt, description, or input
Change the named input, then make a deliberate new request with a new key. Do
not automatically retry identical rejected input. On a failed task, inspect
refunded and creditsCharged separately; a retry recommendation is not a
refund receipt. An unknown reason is not proof of a copyright match.
message and errorMessage text is for people; it can change and is not a
stable contract. When a failure’s internal details cannot be shown, an Omn V1
music video reports a generic message with an unchanged errorCode:
Where
Message
Task errorMessage (read, list, stream and webhooks), MVView.lastErrorMessage and failureReason.message, and failureMessage on GET /api/v1/mv/{mvId}/final
This MV could not be processed. Please retry later with a new idempotency key.
MVView.scenes[].sourceJob.errorMessage
This scene could not be rendered. Edit the scene to render it again.
Change the request, render tier or schedule, or choose another MV engineVersion. An MV that is not_eligible for an upgrade stays as delivered; MVView.capabilities.upgrade reports this before you request one. See Omn V1 rejections.
Omn V1 MV busy or incomplete (MV_PRECONDITION_FAILED, 409, reason upgrade_in_progress, operation_in_progress or mv_not_complete)
Yes, after the blocking work finishes
Wait for the running operation, or finish and recompose pending edits, then retry with the same key and body. rendering_superseded is not retryable: choose a current rendering. See Omn V1 upgrades.
Required source media is unavailable; the new operation was rejected before charging. A temporary verification failure instead returns retryable 503 MV_PROVIDER_UNAVAILABLE. See Source media.
Omn V1 Task ended before rendering (MV_NATIVE_SHOT_PROMPT_TOO_LONG, MV_NATIVE_REFERENCE_REJECTED)
No
The Task is refunded; change the prompt or reference images and create a new Task. See Omn V1 during generation.
