( Globally consistent, fast ) - choose two

@unkey/ratelimit is a library for fast global ratelimiting in serverless functions.

We use Cloudflare workers and Durable Objects to orchestrate low latency ratelimiting at the edge, without sacrificing consistency.


const { success } = await unkey.limit("my-user-id")
if (!success){
  // reject request
// handle request



npm install @unkey/ratelimit

Configure your ratelimiter

import { Ratelimit } from "@unkey/ratelimit"

const unkey = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY,
  namespace: "my-app",
  limit: 10,
  duration: "30s",
  async: true

Use it

async function handler(request) {

const identifier = request.getUserId() // or ip or anything else you want

const ratelimit = await unkey.limit(identifier)
if (!ratelimit.success){
  return new Response("try again later", { status: 429 })

// handle the request here


Making it bullet proof

Everything we do is built for scale and stability. We built on some of the world’s most stable platforms (Planetscale and Cloudflare) and run an extensive test suite before and after every deployment.

Even so, we would be fools if we wouldn’t explain how you can put in safe guards along the way.

In case of severe network degredations or other unforseen events, you might want to put an upper bound on how long you are willing to wait for a response from unkey. By default the SDK will reject a request if it hasn’t received a response from unkey within 5 seconds. You can tune this via the timeout config in the constructor (see below).

The SDK captures most errors and handles them on its own, but we also encourage you to add a onError handler to configure what happens in case something goes wrong.

import { Ratelimit } from "@unkey/ratelimit"

// In this example we decide to let requests pass, in case something goes wrong.
// But you can of course also reject them if you want.
const fallback = { success: true, limit: 0, reset: 0, remaining: 0 }

const unkey = new Ratelimit({
  // ... standard stuff
  timeout: {
    ms: 3000, // only wait 3s at most before returning the fallback
  onError: (err) => {
    return fallback

const { success } = await unkey.limit(identifier)


new Ratelimit(config: RatelimitConfig)

Create a new instance for ratelimiting by providing the necessary configuration.


.limit(identifier: string, opts: LimitOptions): Promise<RatelimitResponse>

Check whether a specific identifier is currently allowed to do something or if they have currently exceeded their limit.