Suno Status and Error Recovery

Lifecycle states

Use the Generation’s clips[] for song delivery. It is the single stable place for provisional IDs, playable URLs, candidate errors, and final output selection. Do not inspect raw outputResults or wait for terminal Task resources[] to discover a candidate.

Generation `status`	Product `phase`	Meaning
`PENDING`	`accepted`	Task exists; provider acknowledgement may not have arrived
`PROCESSING`	`generating`	Candidates are being created or enriched
`PROCESSING`	`finalizing`	Required post-processing such as Extend’s automatic Concat is running
`COMPLETED`	`completed`	Required product output is complete
`FAILED`	`failed`	Required generation or finalization failed
`CANCELLED`	`failed`	Task was cancelled; inspect billing for settlement

Clip `deliveryStatus`	Client behavior
`submitted`	Provider accepted the operation but has not queued a usable clip snapshot.
`queued`	Keep polling the Generation; do not resubmit.
`streaming`	Play when `playable: true` and `playback.url` is non-null; `audioUrl` may still be null.
`complete`	Persist the desired candidate; for Extend prefer `role: "final"`.
`error`	Inspect that clip’s `errorCode` / `errorMessage`; sibling clips may still succeed.

Use webhooks for long-running production workflows. Polling clients should honor viewUrl and back off. The separate Task remains the billing and execution record.

Content policy

A CONTENT_POLICY_REJECTED response or terminal task has retryable: false. Inspect errorReason, actionRequired and rejectedField, correct the input, and make a deliberate new request. Do not retry identical rejected input. See Content policy rejections.

Error codes

Immediate HTTP errors use { success: false, error: { code, message, details? } }. Provider failures that occur after task creation appear on the terminal Task and Generation instead.

Code	Surface	Retry	Meaning
`VALIDATION_ERROR`	HTTP `400`	No	Missing, conflicting, unknown, or unsupported request fields
`INVALID_API_KEY`	HTTP `401`	No	API key is missing, malformed, inactive, or expired
`FORBIDDEN`	HTTP `403`	No	Key scope/IP restriction, or a billing hold blocking paid creation
`INSUFFICIENT_CREDITS`	HTTP `402`	No	Balance was insufficient; no Task was created
`NOT_FOUND` / `TASK_NOT_FOUND`	HTTP `404`	No	Product, clip, Voice, or Task is unavailable to the caller
`RATE_LIMITED`	HTTP `429`	Yes	Respect `Retry-After` or use exponential backoff
`SUNO_INPUT_INVALID`	Terminal Task	No	Unsupported value or resource combination reached the provider workflow
`SUNO_RESOURCE_ACCESS_DENIED`	Terminal Task	No	Referenced clip or Voice cannot be used for this operation
`SUNO_FINALIZATION_FAILED`	Terminal Task	Yes	Intermediate output exists, but required post-processing did not complete
`SUNO_LYRICS_PAIR_TEMPORARILY_UNAVAILABLE`	Terminal Lyrics Pair Task	Yes	Both requested lyrics candidates were not delivered; the Task fails atomically and is refunded
`SUNO_TEMPORARILY_UNAVAILABLE`	Terminal Task	Yes	Capacity, cooldown, verification, or provider delivery is transient
`SUNO_OPERATION_FAILED`	Terminal Task	No	Operation failed without a safer public retry classification
`SUNO_VOICE_SESSION_EXPIRED`	HTTP `409`	No	Verification session is no longer usable; request a new phrase
`SUNO_VOICE_VERIFICATION_PHRASE_MISMATCH`	Terminal Voice Task	No	Verification recording did not contain the assigned complete phrase
`SUNO_VOICE_PIPELINE_COMPATIBILITY_FAILED`	Terminal Voice Task	Yes	Managed Voice preparation encountered a retryable compatibility failure

Generation reads expose the same retry decision as the execution Task, with a customer-safe failureReason. retryable: true on a failed Task means you may create a new logical request later, using a new Idempotency-Key. It does not restart the failed Task or guarantee success. A cancelled or still-processing Task does not grant a new retry permission.

Terminal task descriptors include retryable and refunded. Never infer billing from HTTP status alone. Signed URLs can expire; refresh the task before download. Retained resources can also expose urlExpiresAt, retainedUntil, and assetStatus; copy durable assets to your own storage before retainedUntil. A signed link never advertises an expiry later than the asset retention deadline.

Warning codes

Warnings do not make a successful Task fail.

Code	Meaning	Suggested action
`SUNO_VOCAL_INTENT_NOT_HONORED`	A non-instrumental Simple request completed, but every candidate was instrumental	Review the prompt or use Custom lyrics; another generation is a new paid Task
`SUNO_ALTERNATE_PROCESSING_USED`	A supported managed fallback produced the requested public output	Inspect the delivered format and settlement; no retry is required when output is acceptable

Webhooks

Pass config.webhookUrl on song, derive, lyrics, export, or Voice creation. OmnAPI sends the shared task.* events and retries delivery according to the platform webhook policy. Authenticate the webhook signature before trusting payload fields.

Webhook payloads describe the execution Task. For songs and derivatives, persist generationId from the create receipt and read GET /api/v1/suno/generations/{generationId} after a webhook to obtain current candidate, finalization, and playable-URL state. There is no separate Suno stream connection to maintain.

See Webhook Events for event names, signature verification, delivery order, and retry timing.

Common pitfalls

Do not pass an OmnAPI task ID where a concrete clipId is required. Read the Generation’s clipIds or clips[].clipId first.
Do not wait for Task resources[] to expose processing candidates. Poll the Generation’s clips[].
Do not send a second Concat request after modern Extend. The final resource is already produced in the same task.
Do not send undocumented delivery fields with WAV requests; OmnAPI manages delivery of the requested clip automatically.
Do not hard-code a song-generation price or apply an old-user discount client-side. Turbo is 25 credits, other published models are 28, and customer pricing can change the receipt. Use creditsRequired, because the server applies the caller’s frozen pricing rule to every paid Suno operation.
If a timed-out write used an Idempotency-Key, do not retry it with a new key. Replay the exact request with the original key or poll the returned/recovered task.
A terminal Lyrics Pair failure is different from an in-flight timeout: retry it later as a new request and, if the failed request supplied an Idempotency-Key, use a new value.
Do not send ids on the modern batch clip read; use clipIds.
Do not treat subscriptionOperationsAvailable: true as access to internal Remaster, Infill, Editor, Video, or Opus routes.

Legacy migration map

Existing integrations can use the /api/legacy/* compatibility routes with the legacy api-key header. x-api-key is also accepted. The formerly published /v1/suno-legacy/* prefix and old root-level paths such as /v1/generate are not mounted. Use /api/legacy/* exactly. Music responses add omnapiTaskId and pollUrl; use those fields for canonical task polling. The legacy taskId field is retained for response compatibility and is not a canonical OmnAPI task UUID.

OmnAPI compatibility endpoint	Modern OmnAPI endpoint
`POST /api/legacy/generate`	Custom/Voice/upload → `/api/v1/suno/songs`; existing-clip Extend/Cover → `/api/v1/suno/clips/{clipId}/derive`
`POST /api/legacy/generate-gpt`	`POST /api/v1/suno/songs` with `mode: "simple"`
`POST /api/legacy/generate/lyric`	`POST /api/v1/suno/lyrics`
`POST /api/legacy/concatenate`	No independent modern endpoint; modern Extend automatically concatenates
`GET /api/legacy/songs`	`GET /api/v1/suno/clips?clipIds=...`
`GET /api/legacy/songs/lyric-stamp`	`GET /api/v1/suno/clips/{clipId}/timeline`
`GET /api/legacy/info`	Dashboard balance plus `GET /api/v1/usage/export` and task settlement fields
`POST /api/legacy/upload`	Combine the upload with `upload-extend` or `upload-cover`; no standalone modern Upload endpoint
`POST /api/legacy/stems`	`POST /api/v1/suno/clips/{clipId}/export` with `format: "stems"`
`POST /api/legacy/generate-wav`	`POST /api/v1/suno/clips/{clipId}/export` with `format: "wav"`