Rate Limits
Limit any route with the Workers Rate Limiting binding: the limiter list, how to add one, and what the approximate counts mean.
Sign-in, sign-up, codes and invitations have their own 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-foris never read. An IPv6 address counts as its whole/64. periodis 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
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
Add an entry to
rateLimits: a uniquename, anamespaceId,limit,period(10 or 60) andscope('ip', or'global'for one counter for everyone):exports: { name: 'RL_EXPORTS', namespaceId: '1007', limit: 20, period: 60, scope: 'ip' },Run
pnpm --filter web exec void prepare:c.env.<name>is typed.Call
limitRequestwith 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.