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
`UNAUTHORIZED`	401	Include the `x-api-key` header.
`INVALID_API_KEY`	401	Confirm the key value or rotate to a new active key.
`API_KEY_EXPIRED`	401	Key past its expiry. Create a new one from the dashboard.
`API_KEY_DISABLED`	403	Key was disabled. Use a different active key.
`FORBIDDEN`	403	Key valid but not authorized for this resource or plan tier.

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). `details.errors` lists each.
`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, or raise `maxCredits` when the error details show an MV budget cap was exceeded.
`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.
`TASK_TIMEOUT`	408 / (task status)	Soft timeout (10 min default). Eligible credits are refunded. Resubmit a fresh task.
`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.

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

Class	Retry?	Notes
Auth / validation (`4xx`, `VALIDATION_ERROR`)	No	Fix the request and re-submit.
`INSUFFICIENT_CREDITS`	No	Top up first, or adjust `maxCredits` if the request was rejected by your own 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.
`TASK_TIMEOUT` (on task)	Resubmit, don’t retry the same id	The previous task is already final.