Overview

Protect any endpoint from abuse — no Redis required

Rate limiting controls how many requests a user, IP, or any identifier can make in a given time window. Unkey provides globally distributed rate limiting that works at the edge — without you managing Redis, Upstash, or any infrastructure.

When to use rate limiting

Prevent abuse

Stop bad actors from hammering your endpoints or scraping your data.

Protect costs

Limit expensive operations (AI calls, database queries) before they blow up your bill.

Fair usage

Ensure no single user monopolizes shared resources.

Compliance

Enforce contractual limits (e.g., 10,000 requests/month on a Basic plan).

How it works

1. Choose an identifier

   Decide what you’re limiting: a user ID, API key, IP address, organization, or any string that uniquely identifies the requester.

2. Set the limit

   Define how many requests are allowed and over what duration. Example: 100 requests per minute.

3. Check on each request

   Call limiter.limit(identifier) and Unkey tells you whether to allow or reject the request.

Quick example

TypeScript

import { Ratelimit } from "@unkey/ratelimit";

const limiter = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY,
  namespace: "my-app",      // Group related limits together
  limit: 10,                // 10 requests...
  duration: "60s",          // ...per minute
});

export async function handler(req: Request) {
  // Use any identifier: user ID, API key, IP, etc.
  const identifier = req.headers.get("x-user-id") ?? getClientIP(req);
  
  const { success, remaining, reset } = await limiter.limit(identifier);
  
  if (!success) {
    return new Response("Too many requests", { 
      status: 429,
      headers: {
        "X-RateLimit-Remaining": "0",
        "X-RateLimit-Reset": reset.toString(),
      }
    });
  }
  
  // Request allowed — continue with your logic
  return new Response(`Hello! ${remaining} requests remaining.`);
}

Standalone vs Key-attached rate limits

Unkey offers two ways to rate limit:

Approach	Best for	How it works
Standalone	Any endpoint, public or private	You call limiter.limit() with any identifier
Key-attached	API key authenticated endpoints	Rate limits are configured per-key and checked during keys.verify()

Standalone is what this section covers — it works anywhere, with or without API keys.

Key-attached rate limits are configured when you create API keys and are automatically enforced during verification.

You can use both! Standalone for public endpoints (login, signup), key-attached for authenticated API calls.

What makes Unkey rate limiting different?

No infrastructure to manage

No Redis clusters, no Upstash accounts, no connection strings. Just install the SDK and go.

Globally distributed

Requests are processed across our globally distributed infrastructure. Your rate limits are checked close to your users, not in a single region.

Timeout and fallback

Configure custom timeout and fallback behavior for resilience when network issues occur.

Per-identifier overrides

Give specific users higher limits without changing code. “User X gets 1000/min instead of 100/min.”

Analytics built in

See which identifiers are hitting limits, when, and how often — in your Unkey dashboard.

Get started

1. Create a root key

   Go to Settings → Root Keys and create a new key with these permissions:

   • ratelimit.*.create_namespace
   • ratelimit.*.limit
2. Install the SDK

   npm install @unkey/ratelimit
   
3. Add to your code

   See the framework guides for complete examples with Next.js, Bun, Express, or Hono.

Next steps

Quickstart

Full walkthrough for your framework.

How it works

Choose between consistency and speed.

Overrides

Give specific users custom limits.

SDK Reference

All configuration options and methods.