> For the complete documentation index, see [llms.txt](https://docs.castmagic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.castmagic.io/reference/plans-and-tiers.md).

# Plans & Tiers

API plan tiers, rate limits, and error conventions.

API endpoints are grouped into three tiers. Your plan determines which tiers you can call, and each endpoint page notes its required tier.

## Tiers

| Tier         | Plans           | Unlocks                                                           |
| ------------ | --------------- | ----------------------------------------------------------------- |
| `core`       | Starter and up  | Transcribe, upload, import, all reads, all transcript formats     |
| `automation` | Team and up     | Webhooks, generation, prompts, chat, translations, speaker writes |
| `platform`   | Business and up | Clip suggestions, renders, usage                                  |

Calling an endpoint above your tier returns `403` with `required_tier` and `current_tier` fields and a message naming the plan that unlocks it.

{% hint style="info" %}
A `403` with `"Your plan does not include API access."` means the plan gate, not a bad key — the account has no active subscription, or its plan's API tier is `none`.
{% endhint %}

## Rate limits

Limits are per key, per minute:

| Tier         | Requests / minute |
| ------------ | ----------------- |
| `core`       | 60                |
| `automation` | 300               |
| `platform`   | 1,000             |

Exceeding the limit returns `429` with a `retry-after` header (in seconds).

## Errors

Errors are returned as JSON in one of two shapes:

```json
{ "error": "human-readable message" }
```

```json
{ "errors": { "field": ["reason"] } }
```

| Status | Meaning                          |
| ------ | -------------------------------- |
| `400`  | Bad or missing parameters        |
| `402`  | Storage limit reached            |
| `403`  | Tier gate or access denied       |
| `404`  | Not found                        |
| `422`  | Upload bytes not yet in storage  |
| `429`  | Rate limited (see `retry-after`) |