Business API errors use the following envelope. Signed playback and media
download services have separate HTTP/error contracts; see
playback errors and
media capacity limits.
Do not assume a media error has error.code.
{
"success": false,
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits to start this task.",
"details": {}
}
}
Business API responses carry X-Request-Id in the headers. Capture it when
available, including on errors; media-host headers can differ. 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.
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
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 option named in details.reason, or choose another MV model. turbo_retired: OneClick Turbo no longer sells — use OneClick or Omn. See Omn rejections.
Omn is rendering as many videos as it can; nothing was charged. After Retry-After (60 seconds), repeat the purchase with the same key and body while the quote is valid, otherwise quote again.
Omn video still being made (CONFLICT, 409, reason video_in_progress)
Yes, once it finishes
Returned by DELETE /api/v2/mv/videos/{id}; cancel or wait, then delete.
Omn HD delivery failed (MV_CENTER_HD_FAILED, Task failure)
No, unchanged
The purchased 1080p or 1440p file could not be produced or had the wrong size. The entire order fails and is refunded; no lower-resolution file is delivered. Refund posting is asynchronous: check the video charges. Check availableResolutions before buying HD again.
The video still failed quality review after automatic repairs; it is not delivered and is refunded in full. Buy again with a new quote and Idempotency-Key, ideally with a clearer brief or references.
Omn edit refused (MV_CENTER_EDIT_REFUSED, 409)
No, unchanged
The edit quote would return allowed: false, or a different candidate selection was sent after adopting. details.refusals[] lists every reason, such as more than 15% of the shots or kept clips no longer available. Nothing was charged; change the edit and quote again. See Edit an Omn video.
One paid edit per video runs at a time. Nothing was charged; buy again after the running edit completes, fails or is cancelled.
Omn edit not waiting for a selection (MV_CENTER_EDIT_NOT_PENDING, 409)
No
Returned by POST /api/v2/mv/videos/{id}/adopt when the video is not an edit waiting for candidate selection (already adopted or finished). Read the video.
Omn edit not available (MV_CENTER_EDIT_UNSUPPORTED, 422)
No
The video cannot be edited (bought before November 14, 2026, or not an Omn video), or a /api/v1/mv call has no Omn equivalent (select rendering, a scene edit with referenceImages or shotType). Nothing was charged.
MV busy or incomplete (MV_PRECONDITION_FAILED, 409, reason operation_in_progress, mv_not_complete or, on Omn MVs bought before November 12, 2026, upgrade_in_progress)
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 Edits.
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 Task ended before rendering (MV_NATIVE_SHOT_PROMPT_TOO_LONG, or MV_NATIVE_REFERENCE_REJECTED on historical Tasks)
No
The Task is refunded; change the prompt or reference images and create a new Task. See Omn status and settlement.
Use the official contact page or email support@omnapi.com. Include the operation, HTTP status, error code, request ID, task ID if received, and UTC time. For webhook setup, include the account and callback URL and request secure signing-secret configuration. Never include your API key or signing secret. Keep the original request and receipt while support investigates; do not create another paid task to test recovery.