For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/modules/rate-limiting.md (or send Accept: text/markdown).
Rate limiting
One limiter for every abuse-sensitive route.
Beginner walkthrough
Prerequisites: Read the two beginner guides below, finish Web local setup, and open this monorepo at its root in your editor. Web settings belong in apps/web/.env.local; Next.js does not read the root .env. /dashboard in the default fake mode is a no-database demo; /auth needs a migrated database.
Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.
1. In the server environment, choose RATE_LIMIT_STORE=postgres for shared production buckets and set PUBLIC_AI_DAILY_BUDGET_MICROUNITS=0 to keep public AI disabled.
2. Set TRUSTED_PROXY_COUNT only to the exact number of controlled proxies that append forwarding headers; do not copy 1 unless that is true for your host.
3. Verify a denied request returns a retry-safe error. If limits differ across instances, check they share Postgres.
For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.
Choose the limiter store
RATE_LIMIT_STORE is memory or postgres. When unset, production selects Postgres and other environments select memory. Shared rate_limit_bucket rows coordinate multiple servers; store failures currently fail open to preserve API availability.
Workspace/user AI submission limits and the public API/MCP limiter protect their separate surfaces. Preserve the existing caller-specific bucket keys when adding routes.
Trust only controlled proxy hops
TRUSTED_PROXY_COUNT ranges from 0–10 and counts reverse proxies that append x-forwarded-for. Zero trusts none and uses a shared unknown bucket; one controlled proxy typically needs 1. An incorrect count lets untrusted forwarded values affect the limiter.
Limit anonymous provider spend
PUBLIC_AI_DAILY_BUDGET_MICROUNITS=0 disables public AI calls. A configured nonnegative daily UTC cap reserves platform spend before provider calls and is separate from each workspace's budget. Test concurrent reservations, reset boundaries and denial before any billable provider attempt.
RATE_LIMIT_STORE=postgres
TRUSTED_PROXY_COUNT=1
PUBLIC_AI_DAILY_BUDGET_MICROUNITS=0Setup and configuration
rate-limit-runtime provides shared limiters wired into the abuse-sensitive surfaces — apiV1Limiter (600 requests/minute) and authLimiter (300 requests/minute) are the shipped presets. Limits key on identity plus route bucket and answer with a retryable 429 carrying Retry-After rather than a generic error.
Extend the existing limiter to new abuse-sensitive endpoints — sign-in, OTP, checkout, task submission, key creation — instead of inventing per-route counters that drift apart.
export const apiV1Limiter = createNamedRateLimiter("api-v1", 600, 60_000);
export const authLimiter = createNamedRateLimiter("auth", 300, 60_000);Implementation workflow
Pick the key carefully: per-user for authenticated actions, per-API-key for public traffic, per-IP only as a last resort for anonymous endpoints. Legitimate bursts get a Retry-After; attacks hit a hard ceiling.
Keep the limiter fail-closed on abuse-sensitive routes — if the store is unreachable, prefer rejecting expensive work over letting it through unbounded.
Verification and troubleshooting
Exercise a limiter until it returns 429 with a sane Retry-After, verify different workspaces get independent buckets, and confirm a burst resolves back to success after the window. Log denials without the request's sensitive payload.