# Errors

> Every error code the Clipbeat REST API and MCP server return, with status codes, response bodies and what to do.

Source: https://docs.clipbeat.app/errors/

Errors use standard HTTP status codes and one JSON shape:

```json
{
  "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

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

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

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.

```json
{
  "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

| `error` | Cause |
| --- | --- |
| `insufficient_scope` | The key does not have the scope this endpoint or tool needs. The message names the scope. See [Scopes](https://docs.clipbeat.app/authentication/#scopes). |

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

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

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

## 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](https://docs.clipbeat.app/content-policy/). |
| `song_too_short` | | The song is shorter than 20 seconds. |

## 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](https://docs.clipbeat.app/rate-limits/) was hit. Wait and retry. |

## 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](mailto:hello@clipbeat.app?subject=API%20error) 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

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`:

```json
{
  "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.
