Ratelimit

@unkey/ratelimit is a library for fast global ratelimiting that runs in any server-side JavaScript runtime — Node.js, Deno, Bun, Cloudflare Workers, AWS Lambda, and other serverless or edge functions.

Install#

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",});

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 degradations or other unforeseen 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.

Both fallback property of the timeout config and onError config are callback functions. They receive the original request identifier as one of their parameters, which you can use to determine whether to reject the request.

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 = (identifier: string) => ({  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    fallback,  },  onError: (err, identifier) => {    console.error(`${identifier} - ${err.message}`);    return fallback(identifier);  },});const { success } = await unkey.limit(identifier);

API#

new Ratelimit(config: RatelimitConfig)#

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

onError: () => ({ success: true, limit: 0, remaining: 0, reset: 0 });

onError: () => ({ success: true, limit: 0, remaining: 0, reset: 0 });

.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.

const res = await rl.limit("identifier", { cost: 4 });

RatelimitResponse#