> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflecto.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

Reflecto enforces rate limits across three independent dimensions — **per
token** (burst + monthly), **per IP** (minute + hour), and **per receiving
user** (daily) — plus a per-request payload-size cap. The intent is that a
runaway script or a leaked token can't degrade other users' delivery, and a
noisy IP can't saturate the auth path before a token even gets validated.

## The limits

<Warning>
  **All MVP users are on the free tier.** Pro quotas below are part of the
  locked spec but the Pro tier itself is not yet available — there is no
  way to upgrade today. Treat the Free column as your actual quota.
</Warning>

| Layer                 | Free   | Pro (planned)         | Window               |
| --------------------- | ------ | --------------------- | -------------------- |
| Per-token burst       | 60 req | 600 req               | rolling 60 s         |
| Per-token monthly     | 500    | 10,000                | calendar month (UTC) |
| Per-receiver-user day | 1,000  | 25,000                | rolling 24 h         |
| Per-IP minute         | 20     | 20                    | rolling 60 s         |
| Per-IP hour           | 200    | 200                   | rolling 60 min       |
| Payload size          | 2 KB   | 2 KB (MVP), 4 KB (V1) | per request          |

Monthly quotas reset at the calendar-month boundary in UTC, matching
Pushover's behavior for muscle memory.

## Response headers

Every `200` and `429` response carries:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1234567890
X-RateLimit-Resource: token_burst
```

`X-RateLimit-Resource` names the *binding* layer — the one with the tightest
margin for this request. Known values: `token_burst`, `token_monthly`,
`receiver_daily`, `ip_minute`, `ip_hour`.

On `429` the server also sets:

```
Retry-After: 30
```

…the number of seconds before retrying makes sense. Respect it; immediate
retries just keep tripping the same gate.

## Ordering guarantees

Counter increments are deliberately ordered so 4xx errors don't burn quota:

1. Per-IP limit (cheapest gate).
2. Token format + lookup.
3. Body validation (`400`).
4. Priority-cap check (`403`).
5. Envelope build + size check (`413`).
6. Per-token burst + monthly + per-receiver-day increments.
7. Dispatch.

A misconfigured client retrying with `priority: "INVALID"` or a 3 KB body
will not exhaust its monthly quota on failed sends.

## Tuning expectations

500 monthly sends covers one or two real automations (a daily backup ping
plus a Pi-hole alert). Power users with many integrations will hit the cap;
that's the intended upgrade trigger. Costs scale to near-zero on FCM/SSE so
the cap will be revisited post-launch based on actual conversion data.