# Rate limits

> Request, import and video limits of the Clipbeat API, the 429 response and how to retry.

Source: https://docs.clipbeat.app/rate-limits/

Limits protect the service and your credits from runaway loops. They are generous for normal use: a video takes
minutes, so a well behaved client makes few requests.

## Limits

| Limit | Applies to | Scope | On limit |
| --- | --- | --- | --- |
| 60 requests per minute | Every REST and MCP request | Per API key (REST and MCP share one budget) | `429`, `retry_after_sec: 5`, `Retry-After: 5` |
| 10 song imports per hour | `POST /v1/songs`, `create_video_from_song_url` with `song_url` | Per account | `429`, `retry_after_sec: 360` |
| 4 new videos per hour | `POST /v1/videos`, `create_video_from_song_url` | Per account | `429`, `retry_after_sec: 900` |
| 1 video in progress | `POST /v1/videos`, `create_video_from_song_url` | Per account | `409 video_in_progress` |
| 5 active API keys | Key creation in Studio | Per account | Revoke a key first |

The per-key limit refills continuously (one request per second), so short bursts are fine. Imports and videos that
fail before they start (for example a rejected brief or a bad link) do not count toward the hourly limits.

## The 429 response

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{ "error": "rate_limited", "message": "Too many requests for this key.", "retry_after_sec": 5 }
```

## Retrying

- Wait at least `retry_after_sec` seconds (or the `Retry-After` header when present) before retrying.
- For other temporary errors (`502`, `503`) retry with exponential backoff: 2, 4, 8, 16 seconds, then give up and show
  the error.
- Do not retry `400`, `401`, `402`, `403`, `404` or `422` without changing the request.
- `POST /v1/videos` is not idempotent. If a start request times out on your side, call `GET /v1/videos?limit=1` before
  starting again: the video may already be running, and a second start returns `409 video_in_progress`.

## Polling budget

Polling one video every 30 seconds uses 2 requests per minute. The per-key limit leaves plenty of room for several
integrations on one key, but one key per integration makes problems easier to trace.

Need higher limits? Write to [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=API%20rate%20limits) with your use
case.
