Errors
Errors use standard HTTP status codes and one JSON shape:
{ "error": "song_processing", "message": "The song is still being processed. Try again in 30 seconds.", "retry_after_sec": 30}| Field | Always | Description |
|---|---|---|
error |
yes | Stable machine code. Branch on this. |
message |
yes | Human readable English sentence. Can change; do not parse it. |
retry_after_sec |
no | Seconds to wait before retrying. |
topup_url |
no | On 402: where the account owner adds credits. |
| other fields | no | Some codes add context, listed below. |
New codes can be added within v1. Handle unknown codes by their HTTP status.
400 Bad Request
Section titled “400 Bad Request”The request is invalid. Fix it before retrying.
error |
Endpoint | Cause |
|---|---|---|
invalid_body |
POST endpoints |
The body is not a JSON object. |
invalid_url |
POST /v1/songs |
url is missing or empty. |
suno_link_not_supported |
POST /v1/songs |
A Suno page link. Send a direct link to the audio file. |
unsupported_link |
POST /v1/songs |
Not an https direct audio, Google Drive or Dropbox link, or not public. |
too_many_redirects |
POST /v1/songs |
The link redirects more than 3 times. |
invalid_audio |
POST /v1/songs |
The link did not return a playable audio file. |
rights_attestation_required |
POST /v1/songs, MCP |
rights_attestation is not true. |
rights_version_required |
POST /v1/songs |
rights_version is missing or not current. The message names the current version. |
invalid_tier |
POST /v1/videos |
tier is not preview, standard, plus or premium. |
invalid_aspect |
POST /v1/videos |
aspect is not 16:9 or 9:16. |
song_required |
MCP create_video_from_song_url |
Neither song_url nor song_id was sent. |
401 Unauthorized
Section titled “401 Unauthorized”error |
Cause |
|---|---|
unauthorized |
No key, a malformed key, a revoked key or a deleted account. The response has WWW-Authenticate: Bearer realm="clipbeat". |
402 Payment Required
Section titled “402 Payment Required”The account does not have enough credits. Nothing was started or charged. The agent or app shows topup_url to the
account owner, who adds credits in Clipbeat Studio. Never ask for card details.
{ "error": "insufficient_credits", "message": "Not enough credits. Ask the account owner to add credits in Clipbeat Studio, then retry.", "available_credits": 40, "available_usd": 2, "required_credits": 280, "required_usd": 14, "topup_url": "https://studio.clipbeat.app/credits"}error |
Cause |
|---|---|
insufficient_credits |
Balance is lower than the tier’s price. required_* is present when known. |
payment_required |
The account has not made its first purchase in Clipbeat Studio yet, which previews need. |
403 Forbidden
Section titled “403 Forbidden”error |
Cause |
|---|---|
insufficient_scope |
The key does not have the scope this endpoint or tool needs. The message names the scope. See Scopes. |
404 Not Found
Section titled “404 Not Found”error |
Endpoint | Cause |
|---|---|---|
not_found |
GET /v1/songs/{id}, GET /v1/videos/{id} |
No such id in this account (ids of other accounts look the same as ids that do not exist). |
song_not_found |
POST /v1/videos, GET /v1/pricing |
song_id does not exist in this account. Import it first. |
409 Conflict
Section titled “409 Conflict”The request is valid but cannot run right now.
error |
Extra fields | Cause and what to do |
|---|---|---|
song_processing |
retry_after_sec: 30 (MCP: song_id, next) |
Lyrics are still being read. Retry after 30 seconds. |
video_in_progress |
video (the running video) |
The account already has a video queued or running. Poll it, then start the next one. |
preview_unavailable |
Previews are not available for this account through the API. Use a full video tier. |
Other 409 codes can come from the video engine (for example engine_off when video making is not enabled for the account), with the
message “The video could not be started.” Nothing is charged. Retry later.
413 Payload Too Large
Section titled “413 Payload Too Large”error |
Cause |
|---|---|
too_large |
The linked file is larger than 100 MB. |
422 Unprocessable Content
Section titled “422 Unprocessable Content”The request is understood but refused. Nothing is charged.
error |
Extra fields | Cause |
|---|---|---|
brief_rejected |
reason (for example protected_name) |
style, character or title names a real person, a celebrity, a protected character or a brand, or asks for unsafe content. See Content policy. |
song_too_short |
The song is shorter than 20 seconds. |
429 Too Many Requests
Section titled “429 Too Many Requests”error |
Extra fields | Cause |
|---|---|---|
rate_limited |
retry_after_sec (and Retry-After header on the per-key limit) |
A rate limit was hit. Wait and retry. |
5xx Server errors
Section titled “5xx Server errors”Temporary problems on Clipbeat’s side. Retry with exponential backoff. If one persists for more than a few minutes, write to hello@clipbeat.app with the time and the endpoint.
| Status | error |
Cause |
|---|---|---|
500 |
internal_error |
Unexpected error. The video was not started. |
502 |
import_failed, link_fetch_failed |
The song could not be downloaded from the link or saved. Check that the link works, then retry. |
503 |
check_failed |
The brief could not be checked right now. Retry. |
503 |
storage_unavailable |
Storage is briefly unavailable. Retry. |
Other 5xx codes are possible. Treat any 5xx as temporary.
Errors inside MCP tools
Section titled “Errors inside MCP tools”MCP tool errors are not JSON-RPC errors. The tool call succeeds at the protocol level and returns a result with
isError: true; the error body above is in structuredContent and, as JSON text, in content[0].text:
{ "jsonrpc": "2.0", "id": 3, "result": { "content": [{ "type": "text", "text": "{\"error\":\"insufficient_credits\",\"message\":\"Not enough credits...\",\"topup_url\":\"https://studio.clipbeat.app/credits\"}" }], "structuredContent": { "error": "insufficient_credits", "message": "Not enough credits...", "topup_url": "https://studio.clipbeat.app/credits" }, "isError": true }}JSON-RPC errors are used only for protocol problems:
| Code | Message | Cause |
|---|---|---|
-32700 |
Parse error | The body is not JSON (HTTP 400). |
-32600 |
Invalid Request | Not a JSON-RPC 2.0 message, or an empty batch. |
-32601 |
Method not found | A method the server does not implement. |
-32602 |
Unknown tool | tools/call with a tool name that does not exist. |
Authentication and rate limit errors on /mcp are plain HTTP 401 and 429 responses, as for REST.