Skip to main content
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

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:
ApproachBest forHow it works
StandaloneAny endpoint, public or privateYou call limiter.limit() with any identifier
Key-attachedAPI key authenticated endpointsRate 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 Redis clusters, no Upstash accounts, no connection strings. Just install the SDK and go.
Requests are processed across our globally distributed infrastructure. Your rate limits are checked close to your users, not in a single region.
See real-time performance metrics at ratelimit.unkey.com — our global latency and throughput benchmarks updated live.
Configure custom timeout and fallback behavior for resilience when network issues occur.
Give specific users higher limits without changing code. “User X gets 1000/min instead of 100/min.”
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

bash 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.
Last modified on March 30, 2026