# Rate Limits

> Limit any route with the Workers Rate Limiting binding: the limiter list, how to add one, and what the approximate counts mean.

*Canonical: https://makerkit.dev/docs/void-cloudflare/operations/rate-limits*

---

Sign-in, sign-up, codes and invitations have their own limits ([Authentication: Rate Limits](../authentication/rate-limits)). This page is for every other public route. The kit limits `/api/health` and `/api/client-errors`; you use the same helper for routes you add (an upload, a contact form).

## The Limiter List

`apps/web/config/rate-limits.config.ts` is the one list. `void.config.ts` turns each entry into a Workers Rate Limiting binding.

| Limiter | Limit | Counted per | Used by |
|---|---|---|---|
| `health` | 60 a minute | visitor | `/api/health` |
| `healthAll` | 600 a minute | all visitors | `/api/health` |
| `clientErrors` | 10 a minute | visitor | `/api/client-errors` |
| `clientErrorsAll` | 300 a minute | all visitors | `/api/client-errors` |
| `uploads` | 10 a minute | visitor | `/api/uploads/:kind` |
| `uploadsAll` | 300 a minute | all visitors | `/api/uploads/:kind` |

- **A visitor** is their `cf-connecting-ip`, which Cloudflare sets. `x-forwarded-for` is never read. An IPv6 address counts as its whole `/64`.
- **`period`** is 10 or 60 seconds: Cloudflare accepts no other.
- **Counts are per Cloudflare location and approximate.** A visitor reaching you through two locations gets two counters, and a shared limiter limits each location on its own. Treat a limit as a brake, not an exact quota.

## Use a Limiter in a Route

```ts
import { limitRequest } from '#/lib/rate-limit.server.ts';

export const POST = defineHandler(async (c) => {
  const limited = await limitRequest({ c, limiter: 'exports' });

  if (limited) {
    return limited;
  }

  // the work
});
```

Over the limit the answer is `429` with `Retry-After` (the period), `Cache-Control: no-store` and `{ "code": "RATE_LIMITED", "retryAfterSeconds": 60 }`. `isLimited` gives a plain boolean when you want to answer differently (the client error route drops the report with a `204`).

Check the limit before any work, and before reading a large body.

## Add a Limiter

1. Add an entry to `rateLimits`: a unique `name`, a `namespaceId`, `limit`, `period` (10 or 60) and `scope` (`'ip'`, or `'global'` for one counter for everyone):

   ```ts
   exports: { name: 'RL_EXPORTS', namespaceId: '1007', limit: 20, period: 60, scope: 'ip' },
   ```
2. Run `pnpm --filter web exec void prepare`: `c.env.<name>` is typed.
3. Call `limitRequest` with the new key.

**Namespace ids are unique in your Cloudflare account.** Another Worker of yours using the same id shares its counters. Change the ids in the file if one is taken.

## When the Binding Is Missing

If the binding is not there (not deployed yet, or removed) or its call fails, the request is allowed and one warning per limiter and reason is logged in each Worker instance. A limiter outage must not take the app down. `pnpm kit:doctor --launch` flags a Worker that declares no `ratelimits`.
