/upstash-ratelimit-js

Upstash Ratelimit Methods (TypeScript)

This document provides a focused, practical reference for all Ratelimit methods. Each section includes direct examples, usage patterns, and common pitfalls.

limit

Primary method for checking and consuming tokens.

const { success, remaining, reset, reason, pending } = await ratelimit.limit(
  identifier,
  {
    rate: 2,          // optional: consume N tokens
    ip: req.ip,       // optional: used for deny‑list checks
    userAgent: ua,    // optional
    country: geo?.country,
  }
);

if (!success) return "blocked";

// In Cloudflare/Vercel Edge, flush async work
context.waitUntil(pending);

Notes:

• rate lets a request consume more than 1 token.
• reason can be: timeout, cacheBlock, denyList, or undefined.
• When analytics or MultiRegion is enabled, always handle pending in serverless environments.

blockUntilReady

Waits for a request to become allowed instead of rejecting immediately.

const { success } = await ratelimit.blockUntilReady("id", 30_000);
if (!success) return "still blocked after timeout";

resetUsedTokens

Clears the state for an identifier.

await ratelimit.resetUsedTokens("user123");

Useful when granting temporary resets or admin overrides.

getRemaining

Read-only view of remaining quota.

const { remaining, reset } = await ratelimit.getRemaining("user123");

Common use cases:

• Dashboard queries
• Showing users their remaining quota

setDynamicLimit

Overrides the global limit at runtime.

await ratelimit.setDynamicLimit({ limit: 5 });   // set
await ratelimit.setDynamicLimit({ limit: false }); // remove

Notes:

• Requires dynamicLimits: true in constructor.
• Applies to all future rate checks.

getDynamicLimit

Fetch the currently active dynamic limit.

const { dynamicLimit } = await ratelimit.getDynamicLimit();

Returns null when no override is active.