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.

LimiterLimitCounted perUsed by
health60 a minutevisitor/api/health
healthAll600 a minuteall visitors/api/health
clientErrors10 a minutevisitor/api/client-errors
clientErrorsAll300 a minuteall visitors/api/client-errors
uploads10 a minutevisitor/api/uploads/:kind
uploadsAll300 a minuteall 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

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):

    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.