Upstash Rate Limiter

UpstashRedisRateLimiter is the Rate Limit component’s serverless backend. It builds on @upstash/ratelimit and Upstash Redis over HTTP REST to enforce distributed limits across instances and edge functions, with no shared in-memory state. It implements the framework’s IRateLimiter interface, so the calling code is identical to any other backend.

What the limiter gives you

Counters live in Upstash Redis, so one limit holds across every instance and region. The HTTP REST transport works in edge functions and short-lived runtimes. You pick the limiting algorithm with a single option: fixed window, sliding window, or token bucket. Upstash rate-limit analytics are on by default, so the dashboard has data to show. And the interface is the same IRateLimiter as the other backends: check, isLimited, reset, and getCount.

Installation

UpstashRedisRateLimiter ships with @talosjs/rate-limit and depends on the Upstash rate-limit and Redis clients.

bun add @talosjs/rate-limit @upstash/ratelimit @upstash/redis

Environment variables

Variable	Required	Purpose
`RATE_LIMIT_UPSTASH_REDIS_URL`	Yes	Upstash Redis REST URL. Missing throws `RateLimitException` (`CONFIG_REQUIRED`).
`RATE_LIMIT_UPSTASH_REDIS_TOKEN`	Yes	Upstash Redis REST token. Missing throws `RateLimitException` (`CONFIG_REQUIRED`).

RATE_LIMIT_UPSTASH_REDIS_URL=https://your-db.upstash.io
RATE_LIMIT_UPSTASH_REDIS_TOKEN=your_rest_token

Both can also be passed through constructor options (url, token), which take precedence over the environment. They are validated when the limiter is constructed, so misconfiguration fails fast.

Options

UpstashRedisRateLimiter accepts an options object as its second constructor argument:

Option	Type	Default	Purpose
`url`	`string`	`RATE_LIMIT_UPSTASH_REDIS_URL`	Override the REST URL.
`token`	`string`	`RATE_LIMIT_UPSTASH_REDIS_TOKEN`	Override the REST token.
`algorithm`	`UpstashAlgorithmType`	sliding window, 120 / 60 s	The limiting algorithm and its parameters.
`prefix`	`string`	`"ratelimit"`	Redis key prefix; falls back to `namespace`.
`namespace`	`string`	`"ratelimit"`	Alias for `prefix`.
`analytics`	`boolean`	`true`	Enable Upstash rate-limit analytics.

Algorithms

The algorithm option is a tagged union. Pick one and supply its parameters:

// Fixed window: limit requests per fixed time bucket
{ type: "fixedWindow", limit: 100, window: "60 s" }

// Sliding window (default): smoother limit over a rolling window
{ type: "slidingWindow", limit: 120, window: "60 s" }

// Token bucket: refillRate tokens per interval, up to maxTokens
{ type: "tokenBucket", refillRate: 10, interval: "10 s", maxTokens: 100 }

window and interval are Upstash Duration strings such as "60 s", "1 m", or "1 h". The default is a sliding window of 120 requests per 60 seconds.

How it works

check(key) calls the underlying limiter and normalizes the result into a RateLimitResultType:

Field	Type	Purpose
`limited`	`boolean`	Whether this request exceeded the limit.
`remaining`	`number`	Requests left in the current window.
`total`	`number`	The configured limit.
`resetAt`	`Date`	When the window resets.

Method	Purpose
`check(key)`	Consume one unit and return the full result.
`isLimited(key)`	Convenience boolean for whether the key is over the limit.
`reset(key)`	Reset the used tokens for a key; returns `true` on success.
`getCount(key)`	Remaining requests for a key.

Usage

Key the limiter by whatever identifies the caller: an IP, a user id, or an API key.

import { container } from "@talosjs/container";
import { UpstashRedisRateLimiter } from "@talosjs/rate-limit";

const limiter = container.get(UpstashRedisRateLimiter);

const result = await limiter.check(`ip:${ip}`);
if (result.limited) {
  return context.response
    .status(429)
    .header(
      "Retry-After",
      String(Math.ceil((result.resetAt.getTime() - Date.now()) / 1000)),
    )
    .json({ error: "Too many requests", resetAt: result.resetAt });
}

return context.response.json({ remaining: result.remaining });

Configure a custom algorithm by subclassing the limiter:

import { decorator } from "@talosjs/rate-limit";
import { UpstashRedisRateLimiter } from "@talosjs/rate-limit";
import { AppEnv } from "@talosjs/app-env";
import { inject } from "@talosjs/container";

@decorator.rateLimit()
export class LoginRateLimiter extends UpstashRedisRateLimiter {
  constructor(@inject(AppEnv) env: AppEnv) {
    super(env, {
      prefix: "login",
      algorithm: { type: "fixedWindow", limit: 5, window: "1 m" },
    });
  }
}

Use in the app

In an @talosjs/app application, pass UpstashRedisRateLimiter to the rateLimiter slot of your App config. The framework registers it and exposes it as the "rateLimiter" container constant.

bun add @talosjs/app @talosjs/rate-limit @upstash/ratelimit @upstash/redis

import { App } from "@talosjs/app";
import { UpstashRedisRateLimiter } from "@talosjs/rate-limit";
import { TerminalLogger } from "@talosjs/logger";

const app = new App({
  routing: { prefix: "/api" },
  loggers: [TerminalLogger],
  rateLimiter: UpstashRedisRateLimiter,
});

await app.run();

With a rate limiter configured, the framework checks it before every route, keyed by the client IP, so you don’t call check() yourself. When a request is over the limit it short-circuits with a 429 Too Many Requests and sets the standard headers automatically:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1719571200

If the limiter backend errors, the check fails open (the request proceeds) and the error is logged, so a transient Upstash outage doesn’t take your API down. To customize the algorithm or limits, register a subclass (see Usage) and pass that class to the rateLimiter slot instead. Set RATE_LIMIT_UPSTASH_REDIS_URL and RATE_LIMIT_UPSTASH_REDIS_TOKEN in your .env.yml (or environment).

Exceptions

UpstashRedisRateLimiter throws RateLimitException (HTTP 429) on misconfiguration or operation failures, carrying a machine-readable key.

Key	When
`CONFIG_REQUIRED`	The REST URL or token is missing from both options and the environment.
`RATE_LIMIT_CHECK_FAILED`	A `check()` call against Upstash failed.
`RATE_LIMIT_RESET_FAILED`	A `reset()` call failed.
`RATE_LIMIT_COUNT_FAILED`	A `getCount()` call failed.

import { RateLimitException } from "@talosjs/rate-limit";

try {
  const result = await limiter.check(`ip:${ip}`);
} catch (error) {
  if (error instanceof RateLimitException) {
    logger.error(`Rate limit error [${error.key}]: ${error.message}`);
  }
  throw error;
}

Choosing limits well

Match the algorithm to the case: sliding window for smooth API limits, fixed window for simple per-minute caps, and token bucket where you want to tolerate bursts. Rate-limit by user id on authenticated routes and by IP on public ones, and give each limiter a distinct prefix. Surface resetAt to clients through a Retry-After header alongside the 429 so they back off correctly. Keep the REST URL and token in .env rather than in source. When several limiters share one Upstash database, a distinct prefix/namespace per limiter keeps their counters from colliding. See the Rate Limit component for the full interface and the other backends.

Getting Started

AI

Framework

Command Line

Upstash Rate Limiter

What the limiter gives you

Installation

Environment variables

Options

Algorithms

How it works

Usage

Use in the app

Exceptions

Choosing limits well

​What the limiter gives you

​Installation

​Environment variables

​Options

​Algorithms

​How it works

​Usage

​Use in the app

​Exceptions

​Choosing limits well

What the limiter gives you

Installation

Environment variables

Options

Algorithms

How it works

Usage

Use in the app

Exceptions

Choosing limits well