# Rate limits & errors

## Rate limits

The Cherry API is rate-limited **per app**: every request authenticated with the same [app credentials](https://portal.cherry.fun/docs/api/authentication.md) shares one budget, regardless of source IP or how many keys you hold.

| Window | Default limit |
|---|---|
| Per minute | 600 requests |
| Per day | 50,000 requests |

The windows are **rolling**: at most 600 requests in any trailing 60 seconds, and 50,000 in any trailing 24 hours: there's no fixed calendar reset. Every request counts as one, reads and writes alike.

When you exceed a limit you get `429 Too Many Requests` with a `Retry-After` header (seconds) and a body telling you which window was hit:

```json
{ "error": "RATE_LIMITED", "reason": "PER_MINUTE_LIMIT_EXCEEDED", "retryAfterSec": 60 }
```

Back off and retry after `Retry-After`. Need higher limits? Contact the Cherry team.

## Errors

All errors return a JSON body with an `error` code and a human-readable `message`.

| Status | Code | Cause |
|---|---|---|
| `400` |  | Invalid request body (validation). |
| `401` |  | Missing / malformed / invalid `Authorization`, or the app isn't active. |
| `403` | `INSUFFICIENT_SCOPE` | Your app lacks the required [scope](https://portal.cherry.fun/docs/api/scopes.md). |
| `403` | `ROOM_NOT_MANAGED_BY_APP` | The room belongs to a different app. |
| `403` | `CANNOT_MODERATE_OWNER` | You tried to moderate the room owner. |
| `403` | `CANNOT_DELETE_ASSIGNED_ROOM` | You tried to delete a room your app didn't create. |
| `404` |  | Room / message / member not found. |
| `429` | `RATE_LIMITED` | Rate limit exceeded (see above). |

## Next steps

- [Endpoint reference](https://portal.cherry.fun/docs/api/reference.md)