⚠️ Error Handling Guide

🔹 Error Types

Error Type	Error Code	Error Message
Validation Error	400	`"The 'mv' field is invalid. The model should be one of: sonic-v6, ..."` (lists every valid model)
Validation Error	400	`"The 'persona_id' field is required when task_type = persona_music."`
Validation Error	400	`"The 'make_instrumental' field should be boolean."`
Validation Error	400	`"The 'custom_mode' field should be boolean."`
Validation Error	400	`"The prompt character length should be less than 3000."`
Validation Error	400	`"The 'gpt_description_prompt' character length should be less than 200."`
Validation Error	400	`"The tags character length should be less than 200."`
Validation Error	400	`"The title character length should be less than 80."`
Validation Error	400	`"description is required."`
Validation Error	400	`"The description character length should be less than 120."`
Validation Error	400	`"name and continue_clip_id are required fields."`
Validation Error	400	`"The name character length should be less than 80."`
Validation Error	400	`"The description character length should be less than 200."`
Validation Error	400	`"task not found."`
Validation Error	400	`"missing task id."`
Unauthorized	401	`"Authorization header is missing."`
Unauthorized	401	`"Invalid authorization format."`
Forbidden	403	`"The remaining credits are not enough. You can buy more one-time credit packs or subscribe."`
Forbidden	403	`"You do not have an active subscription. Please check whether your renewal was successful."`
Task rejected / failed	200 (polling) · 400 (create)	Content rejections (copyright, artist names, moderation) and generation failures. The HTTP status is not the signal — read `reason_code` below. On `GET /api/v1/sonic/task/{task_id}` every task failure answers `200` with `type` `"forbidden"`, `"api_error"` or `"failed"`.
Not Found	400	`"task not found."`
Timeout	200	`"Task failed due to timeout. Credits have been refunded."` with `reason_code: "timeout"`
Server Error	500	`"Internal Server Error."`

🔹 Rejection reason codes (`reason_code`)

Added 2026-10-12. Every task that is rejected or fails during generation now carries two extra fields, so you can tell a content rejection from a temporary problem without parsing the message text:

reason_code: one of the values below

retriable: true if the same request may succeed when sent again

`reason_code`	Meaning	`retriable`	What to do
`copyright`	Copyrighted lyrics, or uploaded audio that matches an existing recording	`false`	Change the input
`artist_name`	An artist or producer name in the tags, lyrics or prompt	`false`	Change the input
`moderation`	Content flagged as inappropriate	`false`	Change the input
`invalid_input`	The request can't be used as given (missing or invalid field, prompt needs rephrasing)	`false`	Change the input
`upstream_busy`	Temporary capacity issue	`true`	Retry after a short wait
`timeout`	Generation timed out	`true`	Retry
`unknown`	Any other failure	`false`	Credits are refunded; a single retry is reasonable

Use reason_code, not the HTTP status, to detect a content rejection. The status depends on where the task was rejected:

At create (POST /api/v1/sonic/create): HTTP 400, type: "validation_error", message in error. No credits are charged.

During generation (GET /api/v1/sonic/task/{task_id}): content rejections return type: "forbidden" with the message in message; other failures return type: "api_error" or "failed". Credits are refunded automatically.

Webhooks: song.failed events carry the same two fields.

The human-readable message is still included and can be shown to your users as is. Example:

{"type": "forbidden", "message": "Your lyrics contain copyrighted material. Please change it and try again.", "reason_code": "copyright", "retriable": false}

Our own request validation (field lengths, invalid values), authentication (401) and credit checks (403) are not task rejections and do not carry reason_code.

A 202 with type: "not_ready" is not a failure: the task is still in progress, so keep polling.

📝 Notes

The generated Sonic CDN URL does not have an expiration time.

A song can only create one persona.

Service Stability:

Sonic v3.5 is less stable than Sonic v4.

However, in terms of generation quality, Sonic v4 is less stable than Sonic v3.5.

📌 Ensure to handle these errors properly in your integration for a smooth user experience.

Error handling

⚠️ Error Handling Guide#

🔹 Error Types#

🔹 Rejection reason codes (reason_code)#

📝 Notes#

⚠️ Error Handling Guide

🔹 Error Types

🔹 Rejection reason codes (`reason_code`)

📝 Notes