# RATE_LIMITED

A rate limit was reached.

- **HTTP class:** 429
- **Retryable:** yes

## What happened

One of the account's rate limits was reached, and `error.limit` names it: `calls_per_minute` (tool calls; writes and reads are counted apart), `finalizes_per_hour` or `deploys_per_day` (publishes, the dashboard's Redeploy included), or `new_sites_per_day` (new sites). The numbers are on the [limits page](https://carnival-staging.dev/docs/limits.md).

## Fix

Read `error.limit` and `error.retry_after_seconds`. `calls_per_minute`: wait, then repeat the same call. A publish limit: combine the remaining changes into one update. `new_sites_per_day`: update an existing site (`site=<slug>`) instead. Never retry in a loop.

## What to tell the user

For an hourly or daily limit, tell the user when publishing works again, in their own time zone.

## Agent hint

The exact `error.hint` text; Carnival fills each `<…>` for the call.

`calls_per_minute`:

```text
Too many calls this minute. Wait retry_after_seconds, then repeat the same call.
```

`finalizes_per_hour`:

```text
This account has published <n> times this hour, the limit. Combine the remaining changes into one update and publish after <time>; tell the user.
```

`deploys_per_day`:

```text
This account has published <n> times this day, the limit. Combine the remaining changes into one update and publish after <time>; tell the user.
```

`new_sites_per_day`:

```text
This account can create <n> new sites per day. Update an existing site (site=<slug>) instead, or create it after <time>.
```

## Related

- [`DEPLOYS_PAUSED`](https://carnival-staging.dev/docs/errors/DEPLOYS_PAUSED.md): Publishing is paused.
- [`REJECTION_COOLDOWN`](https://carnival-staging.dev/docs/errors/REJECTION_COOLDOWN.md): Publishing is paused after repeated rejections.
- [`LIVE_SITE_LIMIT_REACHED`](https://carnival-staging.dev/docs/errors/LIVE_SITE_LIMIT_REACHED.md): Every live-site slot is in use.

All error codes: [error codes](https://carnival-staging.dev/docs/errors.md)