Skip to content

    API documentation

    OmnAPI Error Codes

    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.

    SituationMeaningRecovery
    Validation/authentication/budget rejection confirmed before creationNo new task was acceptedCorrect the stated issue, then retry
    Error contains taskId or pollUrlA task exists; its settled state determines the final chargeQuery that task
    HTTP 5xx, connection lost, or local timeout with no receiptSubmission outcome may be unknownReplay the original route/body with the saved idempotency key
    Polled task is FAILED or CANCELLEDThe task is terminalInspect 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.

    CodeHTTPRecovery
    INVALID_API_KEY401Include x-api-key; confirm the value is active and unexpired, or rotate it.
    FORBIDDEN403Inspect 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.
    CodeHTTPRecovery
    BAD_REQUEST400Fix malformed JSON or a structurally missing required field.
    VALIDATION_ERROR400Field present but invalid (range, length, enum). Read structured entries from details.issues[]; details.errors is a legacy serialized summary.
    MISSING_REQUIRED_FIELD400The named field is required.
    INVALID_MODEL400Use a documented model path or omit the model override.
    INVALID_FEATURE400Use a feature supported by the selected model and endpoint.
    FEATURE_NOT_SUPPORTED400Upgrade plan access or remove the unsupported feature.
    CodeHTTPRecovery
    BALANCE_NOT_INITIALIZED402Account balance is not ready yet. Open the dashboard once, then retry.
    CREDIT_DEDUCTION_FAILED500Recover the original request with the same idempotency key; check any returned taskId before a new attempt.
    CREDIT_REFUND_FAILED500File a ticket with X-Request-Id.
    CodeHTTPRecovery
    TASK_NOT_FOUND404Confirm the task id and that the task is still available.
    TASK_ALREADY_EXISTS409Idempotency collision (rare). Re-poll the original id.
    CONFLICT409Generic state/idempotency conflict (e.g. competing edit). Re-poll or reconcile, then retry.
    TASK_CREATION_FAILED500Recover with the original idempotency key and body; poll a returned taskId.
    TASK_EXECUTION_FAILED500 / (task status)Generation failed after the task was accepted. Inspect errorMessage; eligible credits are refunded unless partial output was billable.
    EXPIREDtask statusThe feature-specific task deadline passed after a final status read. Inspect retryable and refunded, then submit a fresh task when retryable.
    PROVIDER_PROCESSING_TIMEOUTtask statusAn accepted generation operation remained non-terminal through its processing deadline. Inspect retryable and refunded, then submit a fresh task when retryable.
    TASK_CANCELLED409 / (task status)Cancelled before completion. Contact support if unexpected.
    CodeHTTPRecovery
    PROVIDER_ERROR502The selected generation service rejected the call. Inspect errorMessage; eligible credits are refunded if surfaced on a task.
    PROVIDER_NOT_FOUND404Use a documented model path or omit the model override.
    PROVIDER_TIMEOUT504The selected generation service did not respond in time. Retry with backoff.
    PROVIDER_RATE_LIMITED429Temporary capacity or rate limit at the selected generation service. Retry after exponential backoff.
    NO_AVAILABLE_ACCOUNT503No generation capacity is currently available. Transient — retry.
    SERVICE_UNAVAILABLE503Gateway in maintenance / shedding load. Retry with backoff.
    SUNO_INPUT_INVALIDtask statusFix the unsupported Suno value or resource combination.
    SUNO_RESOURCE_ACCESS_DENIEDtask statusUse a resource compatible with the requested operation; do not blind-retry.
    SUNO_FINALIZATION_FAILEDtask statusInspect refunded, then retry later with a new idempotency key.
    SUNO_TEMPORARILY_UNAVAILABLEtask statusBack off and retry a new attempt after the temporary service condition clears.
    SUNO_OPERATION_FAILEDtask statusNon-retryable Suno failure; inspect the request and contact support with X-Request-Id.
    CodeHTTPRecovery
    RATE_LIMITED429Respect the Retry-After header. See Rate Limits.
    CodeHTTPRecovery
    INTERNAL_SERVER_ERROR500Unexpected platform error. Capture X-Request-Id and file a ticket.
    NOT_FOUND404Confirm the HTTP method and URL.

    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:

    FieldMeaning
    errorReason / reasoncopyright_similarity, audio_recording_match, artist_reference, content_policy, or unknown
    actionRequiredmodify_lyrics, replace_audio, remove_artist_reference, or modify_input
    rejectedFieldThe 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:

    WhereMessage
    Task errorMessage (read, list, stream and webhooks), MVView.lastErrorMessage and failureReason.message, and failureMessage on GET /api/v1/mv/{mvId}/finalThis MV could not be processed. Please retry later with a new idempotency key.
    MVView.scenes[].sourceJob.errorMessageThis scene could not be rendered. Edit the scene to render it again.

    Branch on errorCode, retryable and refunded. See Omn status and settlement and, for /api/v2/mv, Errors and retries (Omn).

    ClassRetry?Notes
    Auth / validation (401, 403, VALIDATION_ERROR)NoFix the request and re-submit.
    INSUFFICIENT_CREDITSNoTop up first, or raise an intentionally low MV/Vidu/Subtitle/Audio Editing maxCredits spend cap.
    Unsupported engine choice (MV_ENGINE_UNSUPPORTED, 422)NoChange 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 quote expired or already bought (VALIDATION_ERROR 400 reason quote_expired; CONFLICT 409 reason quote_already_used)No, unchangedExpired: quote again and use a new Idempotency-Key. Already bought: do not buy again; read the video in details.taskId.
    Omn busy (MV_PROVIDER_UNAVAILABLE, 503, reason capacity_unavailable)Yes, after Retry-AfterOmn 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 finishesReturned by DELETE /api/v2/mv/videos/{id}; cancel or wait, then delete.
    Omn HD delivery failed (MV_CENTER_HD_FAILED, Task failure)No, unchangedThe 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.
    Omn singer unavailable (MV_CENTER_SINGER_UNAVAILABLE, Task failure)No, unchangedSupply a clear single-person performer image. The failed singing order is refunded in full.
    Omn quality rejected (MV_CENTER_QUALITY_FAILED, Task failure)No, unchangedThe 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, unchangedThe 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.
    Omn edit already running (MV_CENTER_EDIT_IN_PROGRESS, 409)Yes, once it finishesOne 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)NoReturned 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)NoThe 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 finishesWait 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.
    Omn source unavailable (MV_PRECONDITION_FAILED, 409, reason source_assets_unavailable)No, unchangedRequired 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)NoThe Task is refunded; change the prompt or reference images and create a new Task. See Omn status and settlement.
    Omn reference check unavailable (MV_NATIVE_REFERENCE_REVIEW_UNAVAILABLE)Yes, laterThe Task is refunded; create it again with a new Idempotency-Key.
    RATE_LIMITEDYes, after Retry-AfterHonor the header.
    Generation-service transient (PROVIDER_TIMEOUT, PROVIDER_RATE_LIMITED, NO_AVAILABLE_ACCOUNT)Yes, with backoff1s → 2s → 4s → 8s → cap 30s, max 5 tries.
    Server error (INTERNAL_SERVER_ERROR, CREDIT_DEDUCTION_FAILED)Yes, with backoffSame schedule.
    EXPIRED / PROVIDER_PROCESSING_TIMEOUT (on task)Resubmit when retryableThe previous task is already final; also inspect refunded before reconciliation.

    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.