Skip to content

Errors

View as Markdown

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.

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.
error Cause
unauthorized No key, a malformed key, a revoked key or a deleted account. The response has WWW-Authenticate: Bearer realm="clipbeat".

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.
error Cause
insufficient_scope The key does not have the scope this endpoint or tool needs. The message names the scope. See Scopes.
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.

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.

error Cause
too_large The linked file is larger than 100 MB.

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.
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.

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.

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.