How rate limiting works

Unkey counts requests per identifier for you, so there’s no counter store to run. Call ratelimit.limit with a user id or customer id, or put the limit on an API key and read it from keys.verifyKey. Both use the same sliding window. When the identifier is over the limit, Unkey still returns HTTP 200. ratelimit.limit sets data.success to false. keys.verifyKey sets data.code to RATE_LIMITED. Your server returns 429 Too Many Requests to the caller, with Retry-After in seconds. reset in the body is Unix milliseconds. Header names Unkey itself sends are on Rate limiting.

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });

export async function handler(request: Request) {
  const userId = request.headers.get("x-user-id") ?? "anonymous";
  const result = await unkey.ratelimit.limit({
    namespace: "api.requests",
    identifier: userId,
    limit: 100,
    duration: 60_000,
  });

  if (!result.data.success) {
    const retryAfter = Math.max(1, Math.ceil((result.data.reset - Date.now()) / 1000));
    return new Response("Too many requests", {
      status: 429,
      headers: { "Retry-After": String(retryAfter) },
    });
  }

  return new Response("ok");
}

A monthly total on an API key is credits, not this window. See Credits and refill. The rest of this page explains how the count is computed.

How requests are counted

A limit is limit requests per duration milliseconds. Unkey uses a sliding window, so a caller can’t use a full limit at the end of one window and another full limit right after. It counts the current window plus part of the previous one, based on how much of the current window is left.

previous window                 current window
|-------------------------------|-------------------------------|
                                       ^ now, 25% into the window

effective count = current + previous * (1 - 0.25)
allowed if effective count + cost <= limit

For example, with a limit of 100 per minute, a caller who made 100 requests at the end of one minute still counts as 75 fifteen seconds into the next (100 × 0.75), so the burst can’t repeat right away. Denied requests don’t count, so retrying while limited doesn’t push the reset further away.

Make some requests cost more

Each check spends cost tokens, 1 by default, so a heavy operation can use more of the limit than a light one. With limit: 100, a caller can make 100 checks at cost 1, 20 at cost 5, or any mix. A cost of 0 reads the current state without spending anything. When one call checks several limits, a request denied by one limit doesn’t use up the others.

How exact the counts are across regions

Each region decides quickly using the traffic it has seen, and regions share counts within moments. In practice:

Situation	What to expect
One region receives most of an identifier’s traffic	Enforcement is tight.
Traffic is split across regions	A short burst can get through in more than one region before the counts catch up.
Part of our infrastructure is down	Limits stay on in each region, but a limit can let through more than usual until counts catch up.

Rate limits protect you from bursts. They aren’t an exact count. Use credits when you need an exact total. See Credits and refill.

What you get back

Field	Meaning
`success`	Whether this request fit within the limit. In `ratelimit.multiLimit` the per-check field is `passed`.
`limit`	The limit that applied: yours, or an override’s if one matched.
`remaining`	Tokens left in the current window, as an estimate; 0 when the check failed.
`reset`	Unix milliseconds when the current window ends. Capacity comes back gradually after this, not all at once.
`overrideId`	The override that supplied `limit` and `duration`, when one matched; empty otherwise.

Trust success as the answer. Treat remaining as a close estimate, because another region may have accepted requests that aren’t counted yet.

What happens on errors

ratelimit.limit and ratelimit.multiLimit reject an empty identifier, a limit below 1, or a duration under 1000 milliseconds. If the check can’t run, they return an error, and your code decides whether to allow or deny. keys.verifyKey is different. If the rate limit check can’t run, the verification carries on as if the limits passed, so an outage can’t lock your users out. The same happens with an inline limit below 1 or a duration under 1000 milliseconds, so check those values before you send them. See Verifying keys.

Get started

Framework guides

Keyspaces

Keys

Rate limiting

Identities

Authorization

Analytics

Developer portal

Security

Cookbook

How rate limiting works

How requests are counted

Make some requests cost more

How exact the counts are across regions

What you get back

What happens on errors

​How requests are counted

​Make some requests cost more

​How exact the counts are across regions

​What you get back

​What happens on errors

How requests are counted

Make some requests cost more

How exact the counts are across regions

What you get back

What happens on errors