Enforce distributed rate limits across serverless functions

Upstash Ratelimit implements distributed request limiting with @upstash/ratelimit and Upstash Redis. Counters live in Redis so multiple serverless function instances or edge workers share the same state instead of keeping independent in-memory allowances. The skill covers fixed windows, sliding windows, token buckets, per-identifier keys, optional analytics, and optional in-memory blocking for identifiers already known to be over their limit.

Algorithm choice follows the required behavior. Sliding windows are recommended for most APIs, token buckets allow short bursts, and fixed windows favor lower Redis cost. A sliding window can guard an API, while separate token-bucket configurations distinguish free and pro plan allowances. Distinct key prefixes keep endpoint or plan counters from colliding. MultiRegionRatelimit exchanges strict accuracy for lower latency and does not support the token-bucket algorithm.

Use this skill to limit requests by user, API key, tenant, or IP across serverless instances or regions. It applies to login, signup, form, webhook, and language-model endpoints that need abuse protection and 429 Too Many Requests responses. It does not handle client-side backoff against a third-party API's rate limits. A single long-running process without shared-state needs may be better served by an in-memory limiter.

An Upstash Redis database and network access are required; the package is not a general client for other Redis servers. Redis checks add HTTP round-trip latency. Sliding windows approximate activity in the previous window rather than preserving an exact request log. The default five-second timeout allows requests through with a timeout reason when Redis is unreachable. This fail-open behavior must be considered alongside the intended protection.

Configuration includes Redis credentials in the environment, a limiting algorithm and allowance, a stable identifier, and a distinct prefix. The documented installation is:

npm install @upstash/ratelimit @upstash/redis

Create the limiter at module scope rather than inside each request handler. This lets its ephemeral cache short-circuit already-blocked identifiers without another Redis call. Use stable identifiers consistently across requests, preferring users, API keys, or tenants and falling back to IP for anonymous traffic. Undefined identifiers or fresh random values can make every request appear to have a new allowance.

Calling limit returns success, limit, remaining, reset, and pending. A false success value indicates that the identifier exceeded its allowance. Reset is a Unix timestamp in milliseconds. Pending represents background work such as analytics or multi-region synchronization, so it must be awaited or passed to the edge runtime's waitUntil mechanism before the function can freeze.

The Next.js middleware example guards API paths and returns 429 with X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers. A proxy-supplied x-forwarded-for value must be validated rather than trusted directly, because clients may spoof it. Empty analytics on Vercel Edge or Cloudflare Workers can indicate that pending background work was cancelled after the response.

The storage integration is @upstash/redis, with examples using Next.js middleware and edge runtime lifecycle hooks. Rate limiting supplements authentication and input validation. The Redis token grants database access and must remain server-side. Production allowance changes can block legitimate users, so stricter numbers require confirmation before deployment and environment-specific validation remains necessary.