Rate Limit

The @talosjs/rate-limit component throttles requests per key, where a key is an IP, a user ID, an API key, or anything else you can name. RedisRateLimiter and UpstashRedisRateLimiter both implement the IRateLimiter interface (check, isLimited, reset, getCount), so the limit can be shared across every instance of your app. Every check returns a structured result with the remaining quota, the total limit, and the exact time the window resets.

How throttling works here

RedisRateLimiter runs on Bun’s native Redis client and UpstashRedisRateLimiter runs on Upstash’s REST API; both implement IRateLimiter. You pass any string to check() (ip:1.2.3.4, user:123, apikey:abc) and each key is throttled on its own. The result carries limited, remaining, total, and resetAt, which is enough to build a Retry-After header and report the remaining quota to clients. Counters live in Redis, so the limit holds across every instance of your app. Both limiters are registered with @talosjs/container and inject AppEnv, so they wire themselves from environment variables. When something fails, the limiter throws RateLimitException, which carries HTTP 429 Too Many Requests and a machine-readable key.

How it works

You resolve a limiter and call check(key) on every request you want to throttle. The backend increments a counter for that key and returns the current state. When limited is true, the caller has exceeded its quota for the current window.

Method	Purpose
`check(key)`	Count this request and return `{ limited, remaining, total, resetAt }`.
`isLimited(key)`	Runs `check()` and returns just the `limited` boolean.
`reset(key)`	Clear the counter for a key; returns whether anything was removed.
`getCount(key)`	Read a backend-specific numeric value without mutating it. `RedisRateLimiter` returns the current counter; `UpstashRedisRateLimiter` returns the remaining quota reported by Upstash.

The RateLimitResultType returned by check():

Field	Type	Meaning
`limited`	`boolean`	`true` once the key has exceeded the allowed requests in the window.
`remaining`	`number`	Requests left before the key is limited (never below `0`).
`total`	`number`	The configured limit for the window.
`resetAt`	`Date`	When the current window expires and the counter resets.

The backend’s window algorithm:

Backend	Algorithm	Default window	Key namespace
`RedisRateLimiter`	Fixed-window counter — `INCR` the key, set a TTL on the first request of the window, and compare against the limit.	120 requests / 60 seconds	`ratelimit:`
`UpstashRedisRateLimiter`	Upstash `slidingWindow` by default (configurable to `fixedWindow` or `tokenBucket`).	120 requests / 60 seconds	`ratelimit:`

RedisRateLimiter namespaces every key as <namespace>:<key> (default namespace ratelimit) so multiple apps can share one Redis instance without colliding.

Environment variables

Variable	Backend	Required	Purpose
`RATE_LIMIT_REDIS_URL`	`RedisRateLimiter`	Yes (unless `connectionString` is passed)	Connection string, e.g. `redis://localhost:6379`. Missing throws `RateLimitException` (`RATE_LIMIT_CONNECTION_FAILED`).
`RATE_LIMIT_UPSTASH_REDIS_URL`	`UpstashRedisRateLimiter`	Yes (unless `url` is passed)	Upstash Redis REST URL. Missing throws `RateLimitException` (`CONFIG_REQUIRED`).
`RATE_LIMIT_UPSTASH_REDIS_TOKEN`	`UpstashRedisRateLimiter`	Yes (unless `token` is passed)	Upstash Redis REST token. Missing throws `RateLimitException` (`CONFIG_REQUIRED`).

RATE_LIMIT_REDIS_URL=redis://localhost:6379

Usage

Resolve a limiter from the container (it reads its connection details from the environment), then call check() on each request you want to throttle.

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

const limiter = container.get(RedisRateLimiter);

// Count this request for the client and inspect the result
const result = await limiter.check("ip:192.168.1.1");

result.limited;   // false while under the limit, true once exceeded
result.remaining; // requests left in the current window
result.total;     // the configured limit
result.resetAt;   // Date the window resets

Reject limited requests and tell the client when to retry:

const result = await limiter.check(`user:${userId}`);

if (result.limited) {
  const retryAfter = Math.ceil((result.resetAt.getTime() - Date.now()) / 1000);
  return new Response("Too Many Requests", {
    status: 429,
    headers: { "Retry-After": String(retryAfter) },
  });
}

Use isLimited() when you only need the boolean, and reset() / getCount() for inspection and administration:

// Boolean-only check
if (await limiter.isLimited(`apikey:${apiKey}`)) {
  return forbidden();
}

// Read the current count without consuming quota
const count = await limiter.getCount("ip:192.168.1.1");

// Clear a key (e.g. after a manual unblock)
const wasReset = await limiter.reset("ip:192.168.1.1");

You can override connection and namespace settings through constructor options instead of the environment:

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

const limiter = new RedisRateLimiter(env, {
  connectionString: "redis://localhost:6379",
  namespace: "api",
});

Decorator and usage

`@decorator.rateLimit()`

Registers a rate limiter class with the container. It accepts an optional scope (defaults to singleton). The packaged limiters are already decorated; use it to register a custom limiter that implements IRateLimiter, or to extend a packaged one under your own name.

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

@decorator.rateLimit()
export class ApiRateLimiter extends RedisRateLimiter {}

Resolve it from the container and inject it where you guard a route:

import { inject } from "@talosjs/container";

export class ApiGuard {
  constructor(@inject(ApiRateLimiter) private readonly limiter: ApiRateLimiter) {}

  public async allow(ip: string): Promise<boolean> {
    return !(await this.limiter.isLimited(`ip:${ip}`));
  }
}

Exceptions

The component throws RateLimitException when a backend is misconfigured or an operation fails. It extends the base Exception, carries the HTTP status 429 Too Many Requests, and exposes a machine-readable key, a human-readable message, and a data object.

Key	When
`RATE_LIMIT_CONNECTION_FAILED`	`RedisRateLimiter` is created without a `connectionString` or `RATE_LIMIT_REDIS_URL`.
`CONFIG_REQUIRED`	`UpstashRedisRateLimiter` is created without a URL or token.
`RATE_LIMIT_CHECK_FAILED`	A `check()` (or `isLimited()`) call against the backend fails.
`RATE_LIMIT_RESET_FAILED`	A `reset()` call against the backend fails.
`RATE_LIMIT_COUNT_FAILED`	A `getCount()` call against the backend fails.

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

try {
  const result = await limiter.check(`user:${userId}`);
  if (result.limited) {
    return tooManyRequests(result);
  }
} catch (error) {
  if (error instanceof RateLimitException) {
    logger.error(`Rate limit error [${error.key}]: ${error.message}`, error.data);
    // Fail open or closed depending on your policy
  } else {
    throw error;
  }
}

Throttling in practice

Pick a stable key scheme. Throttling by ip:, user:, or apikey: prefixes limits each identity on its own and lets reset() target a single entry. Derive your Retry-After header from result.resetAt so clients back off for the right amount of time instead of hammering the endpoint. Reach for isLimited() when you only need to allow or deny, and the full check() result when you want to report remaining quota to the caller. Decide up front whether you fail open or closed: wrap check() in try/catch and pick deliberate behavior for when Redis is unreachable, since rejecting all traffic on a backend outage may be worse than letting it through. When several services share one Redis, give each a distinct namespace so counters never collide. And prefer container.get() or @inject over new, so configuration flows from AppEnv and the limiter stays a singleton.

Getting Started

AI

Framework

Command Line

How throttling works here

How it works

Environment variables

Usage

Decorator and usage

`@decorator.rateLimit()`

Exceptions

Throttling in practice

​How throttling works here

​How it works

​Environment variables

​Usage

​Decorator and usage

​@decorator.rateLimit()

​Exceptions

​Throttling in practice

How throttling works here

How it works

Environment variables

Usage

Decorator and usage

`@decorator.rateLimit()`

Exceptions

Throttling in practice