OmnAPI Error Codes

Response shape

Every error follows the same envelope:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to start this task.",
    "details": { /* optional, context-specific */ }
  }
}

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.

When errors appear

Errors come in two flavors:

Where	What it means
HTTP status 4xx / 5xx on the original POST	Submission was rejected; no task was created
status: "FAILED" on a polled task descriptor	Submission accepted but generation failed downstream

The first kind does not charge credits. The second usually refunds eligible credits automatically; partial-output cases may keep a smaller final charge.

Code reference

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.

Authentication & authorization

Code	HTTP	Recovery
INVALID_API_KEY	401	Include x-api-key; confirm the value is active and unexpired, or rotate it.
FORBIDDEN	403	Add the required scope or call from an allowed IP. Inspect details.requiredScope / details.clientIp when present.

Request validation

Code	HTTP	Recovery
BAD_REQUEST	400	Fix malformed JSON or a structurally missing required field.
VALIDATION_ERROR	400	Field present but invalid (range, length, enum). Read structured entries from details.issues[]; details.errors is a legacy serialized summary.
MISSING_REQUIRED_FIELD	400	The named field is required.
INVALID_MODEL	400	Use a documented model path or omit the model override.
INVALID_FEATURE	400	Use a feature supported by the selected model and endpoint.
FEATURE_NOT_SUPPORTED	400	Upgrade plan access or remove the unsupported feature.

Credits & billing

Code	HTTP	Recovery
INSUFFICIENT_CREDITS	402	Add credits from the dashboard. For MV or Vidu, 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	Credits were not actually charged. Safe to retry.
CREDIT_REFUND_FAILED	500	File a ticket with X-Request-Id.

Task lifecycle

Code	HTTP	Recovery
TASK_NOT_FOUND	404	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	Transient — retry.
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.

Generation services

Code	HTTP	Recovery
PROVIDER_ERROR	502	The selected generation service rejected the call. Inspect errorMessage; eligible credits are refunded if surfaced on a task.
PROVIDER_NOT_FOUND	404	Use a documented model path or omit the model override.
PROVIDER_TIMEOUT	504	The selected generation service did not respond in time. Retry with backoff.
PROVIDER_RATE_LIMITED	429	Temporary capacity or rate limit at the selected generation service. Retry after exponential backoff.
NO_AVAILABLE_ACCOUNT	503	No generation capacity is currently available. Transient — retry.
SERVICE_UNAVAILABLE	503	Gateway in maintenance / shedding load. Retry with backoff.
SUNO_INPUT_INVALID	task status	Fix the unsupported Suno value or resource combination.
SUNO_RESOURCE_ACCESS_DENIED	task status	Use a resource compatible with the requested operation; do not blind-retry.
SUNO_FINALIZATION_FAILED	task status	Inspect refunded, then retry later with a new idempotency key.
SUNO_TEMPORARILY_UNAVAILABLE	task status	Back off and retry a new attempt after the temporary service condition clears.
SUNO_OPERATION_FAILED	task status	Non-retryable Suno failure; inspect the request and contact support with X-Request-Id.

Rate limits

Code	HTTP	Recovery
RATE_LIMITED	429	Respect the Retry-After header. See Rate Limits.

Catch-all

Code	HTTP	Recovery
INTERNAL_SERVER_ERROR	500	Unexpected platform error. Capture X-Request-Id and file a ticket.
NOT_FOUND	404	Confirm the HTTP method and URL.

Retry decision matrix

Tip

The “should I retry?” answer in one table.

Class	Retry?	Notes
Auth / validation (4xx, VALIDATION_ERROR)	No	Fix the request and re-submit.
INSUFFICIENT_CREDITS	No	Top up first, or raise an intentionally low MV/Vidu maxCredits spend cap.
RATE_LIMITED	Yes, after Retry-After	Honor the header.
Generation-service transient (PROVIDER_TIMEOUT, PROVIDER_RATE_LIMITED, NO_AVAILABLE_ACCOUNT)	Yes, with backoff	1s → 2s → 4s → 8s → cap 30s, max 5 tries.
Server error (INTERNAL_SERVER_ERROR, CREDIT_DEDUCTION_FAILED)	Yes, with backoff	Same schedule.
EXPIRED / PROVIDER_PROCESSING_TIMEOUT (on task)	Resubmit when retryable	The previous task is already final; also inspect refunded before reconciliation.