Rate limiting reference
Arcjet rate limiting lets you define rules which limit the number of requests a client can make over a period of time.
Configuration
Section titled “Configuration”Each rate limit is configured on an exact path with a set of client characteristics and algorithm specific options.
Fixed window rate limit options
Section titled “Fixed window rate limit options”Tracks the number of requests made by a client over a fixed time window. Options are explained in the Configuration documentation. For more details about how the algorithm works, see the fixed window algorithm description.
// Options for fixed window rate limit// See https://docs.arcjet.com/rate-limiting/configurationtype FixedWindowRateLimitOptions = { // "LIVE" will block requests. "DRY_RUN" will log only mode?: "LIVE" | "DRY_RUN"; // How the client is identified. See https://docs.arcjet.com/fingerprints characteristics?: string[]; // Time window the rate limit applies to (for example, "1h", "60s", or seconds as a number) window: string | number; // Maximum number of requests allowed in the time window max: number;};# Signature for arcjet.fixed_window# See https://docs.arcjet.com/rate-limiting/configurationdef fixed_window( *, # Required. Mode.LIVE blocks requests; Mode.DRY_RUN logs only. mode: Mode, # Time window in seconds the rate limit applies to (integer only – Python # does not accept the "1h"/"60s" duration strings that the JS SDK does). window: int, # Maximum number of requests allowed in the time window max: int, # How the client is identified. See https://docs.arcjet.com/fingerprints characteristics: Sequence[str] = (),) -> FixedWindow: ...Fixed window example
Section titled “Fixed window example”import { fixedWindow } from "@arcjet/nest";
// ...// This is part of the rules constructed using withRule or a guard// ...fixedWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only window: "60s", // 60 second fixed window max: 100, // allow a maximum of 100 requests});Sliding window rate limit options
Section titled “Sliding window rate limit options”Tracks the number of requests made by a client over a sliding window so that the window moves with time. Options are explained in the Configuration documentation. For more details about how the algorithm works, see the sliding window algorithm description.
// Options for sliding window rate limit// See https://docs.arcjet.com/rate-limiting/configurationtype SlidingWindowRateLimitOptions = { // "LIVE" will block requests. "DRY_RUN" will log only mode?: "LIVE" | "DRY_RUN"; // How the client is identified. See https://docs.arcjet.com/fingerprints characteristics?: string[]; // The time interval in seconds for the rate limit interval: number; // Maximum number of requests allowed over the time interval max: number;};# Signature for arcjet.sliding_window# See https://docs.arcjet.com/rate-limiting/configurationdef sliding_window( *, # Required. Mode.LIVE blocks requests; Mode.DRY_RUN logs only. mode: Mode, # The time interval in seconds for the rate limit interval: int, # Maximum number of requests allowed over the time interval max: int, # How the client is identified. See https://docs.arcjet.com/fingerprints characteristics: Sequence[str] = (),) -> SlidingWindow: ...Sliding window example
Section titled “Sliding window example”import { slidingWindow } from "@arcjet/nest";
// ...// This is part of the rules constructed using withRule or a guard// ...slidingWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only interval: 60, // 60 second sliding window max: 100, // allow a maximum of 100 requests});Token bucket rate limit options
Section titled “Token bucket rate limit options”Based on a bucket filled with a specific number of tokens. Each request withdraws a token from the bucket and the bucket is refilled at a fixed rate. Once the bucket is empty, the client is blocked until the bucket refills. Options are explained in the Configuration documentation. For more details about how the algorithm works, see the token bucket algorithm description.
// Options for token bucket rate limit// See https://docs.arcjet.com/rate-limiting/configurationtype TokenBucketRateLimitOptions = { // "LIVE" will block requests. "DRY_RUN" will log only mode?: "LIVE" | "DRY_RUN"; // How the client is identified. See https://docs.arcjet.com/fingerprints characteristics?: string[]; // Number of tokens to add to the bucket at each interval refillRate: number; // The interval in seconds to add tokens to the bucket interval: number; // The maximum number of tokens the bucket can hold capacity: number;};# Signature for arcjet.token_bucket# See https://docs.arcjet.com/rate-limiting/configurationdef token_bucket( *, # Required. Mode.LIVE blocks requests; Mode.DRY_RUN logs only. mode: Mode, # Number of tokens to add to the bucket at each interval refill_rate: int, # The interval in seconds to add tokens to the bucket interval: int, # The maximum number of tokens the bucket can hold capacity: int, # How the client is identified. See https://docs.arcjet.com/fingerprints characteristics: Sequence[str] = (),) -> TokenBucket: ...When using a token bucket rate limit, each request must specify the number of
tokens it wishes to withdraw from the bucket. This is done by passing a
requested property to the protect function.
Token bucket example
Section titled “Token bucket example”For how to specify the number of tokens to request, see the token bucket request example.
import { tokenBucket } from "@arcjet/nest";
// ...// This is part of the rules constructed using withRule or a guard// ...tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 10, // refill 10 tokens per interval interval: 60, // 60 second interval capacity: 100, // bucket maximum capacity of 100 tokens});The amount of tokens to deduct from the bucket is specified in the requested
option as a positive integer when calling the Arcjet protect function.
// Deduct 50 tokens from the bucket// The value for `requested` must be a positive integerconst decision = await aj.protect(req, { requested: 50 });# Deduct 50 tokens from the bucket# The value for `requested` must be a positive integerdecision = await aj.protect(request, requested=50) # use aj.protect(request, ...) for arcjet_syncIdentify users
Section titled “Identify users”Rate limit rules use characteristics to identify the client and apply the
limit across requests. The default is to use the client’s IP address. However,
you can specify other
characteristics such as a user ID
or other metadata from your application.
In this example we define a rate limit rule that applies to a specific user ID.
The custom characteristic is userId with the value passed as a prop on the
protect function. You can use any string for the characteristic name and any
string, number or boolean for the value.
import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageAdvancedService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file, such as:// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageAdvancedController { constructor( private readonly pageService: PageAdvancedService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( fixedWindow({ // characteristics can also be set on the client in app.module.ts characteristics: ["userId"], mode: "LIVE", window: "1h", max: 60, }), ) .protect(req, { userId: "user123" });
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}To identify users with different characteristics, such as IP address for anonymous
users and a user ID for logged in users, you can use withRule (JS) or
with_rule() (Python) to create augmented clients that use different
characteristics. See the
example in the custom characteristics section.
Guards and routes
Arcjet can be integrated into NestJS in several places using NestJS guards or directly within the route controller:
- Global guard: Applies Arcjet rules on every request, but doesn’t let you configure rules per route.
- Per route guard: Lets you configure rules per route, but requires you to add the guard to every route and has limited flexibility.
- Within route: Requires some code duplication, but allows maximum flexibility because you can customize the rules and response.
Global guard
A global guard can be configured in src/app.module.ts.
import { ArcjetModule, fixedWindow } from "@arcjet/nest";import { Module } from "@nestjs/common";import { ConfigModule } from "@nestjs/config";
@Module({ imports: [ ConfigModule.forRoot({ isGlobal: true, envFilePath: ".env.local", }), ArcjetModule.forRoot({ isGlobal: true, key: process.env.ARCJET_KEY!, rules: [ // Applies to every request fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ], }), // ... other modules ],})export class AppModule {}This can then be added to the controller for all the routes you wish to protect with Arcjet.
import { ArcjetGuard } from "@arcjet/nest";import { Controller, Get, Injectable, UseGuards } from "@nestjs/common";
// This would normally go in your controller file, such as:// src/page/page.controller.ts@Controller("page")// Uses the ArcjetGuard to protect the controller with the default rules defined// in app.module.ts. Using a guard makes it easy to apply Arcjet rules, but you// don't get access to the decision.@UseGuards(ArcjetGuard)export class PageController { constructor(private readonly pageService: PageService) {}
@Get() index() { return this.pageService.message(); }}
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}Per route guard
A per route guard can be configured in the controller for each route you wish to
protect with specific Arcjet rules. The client created in src/app.module.ts
is automatically passed to the guard.
Arcjet applies the rules and returns a generic error if the result is DENY.
import { WithArcjetRules, fixedWindow } from "@arcjet/nest";import { Injectable, Get } from "@nestjs/common";
// This would normally go in your controller file, such as:// src/page/page.controller.ts// Attaches the ArcjetGuard to the controller to protect it with the specified// rules extended from the global rules defined in app.module.ts.@WithArcjetRules([ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }),])export class PageController { constructor(private readonly pageService: PageService) {}
@Get() index() { return this.pageService.message(); }}
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}Within route
Call Arcjet from within the route controller to have maximum flexibility.
import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageAdvancedService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file, such as:// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageAdvancedController { constructor( private readonly pageService: PageAdvancedService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}Decision
Section titled “Decision”Arcjet provides a single protect function that is used to execute your
protection rules. This requires a RequestEvent property which is the event
context as passed to the request handler.
If you are using a global guard or per route
guard then protect is called for you behind the scenes. If you add Arcjet
within a route then you call it directly.
This function returns a Promise that resolves to an
ArcjetDecision object. This contains the following properties:
id(string) – The unique ID for the request. This can be used to look up the request in the Arcjet dashboard. It is prefixed withreq_for decisions involving the Arcjet cloud API. For decisions taken locally, the prefix islreq_.conclusion(ArcjetConclusion) – The final conclusion based on evaluating each of the configured rules. If you wish to accept Arcjet’s recommended action based on the configured rules then you can use this property.reason(ArcjetReason) – An object containing more detailed information about the conclusion.results(ArcjetRuleResult[]) – An array ofArcjetRuleResultobjects containing the results of each rule that was executed.ip(ArcjetIpDetails) – An object containing Arcjet’s analysis of the client IP address. For more information, see the SDK reference.
To check whether a rate limit rule returned a deny conclusion, use
decision.isDenied() and decision.reason.isRateLimit() (JS) /
decision.is_denied() and decision.reason_v2.type == "RATE_LIMIT" (Python).
You can iterate through the results and check whether a rate limit was applied:
for (const result of decision.results) { console.log("Rule Result", result);}for result in decision.results: print("Rule Result", result)This example logs the full result as well as each rate limit rule:
import { ARCJET, type ArcjetNest, detectBot, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Logger, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file, such as:// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { // Make use of the NestJS logger: https://docs.nestjs.com/techniques/logger // See // https://github.com/arcjet/example-nestjs/blob/ec742e58c8da52d0a399327182c79e3f4edc8f3b/src/app.module.ts#L29 // and https://github.com/arcjet/example-nestjs/blob/main/src/arcjet-logger.ts // for an example of how to connect Arcjet to the NestJS logger private readonly logger = new Logger(PageController.name);
constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only // configured with a list of bots to allow from // https://arcjet.com/bot-list allow: [], // blocks all automated clients }), ) .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
this.logger.log(`Arcjet: id = ${decision.id}`); this.logger.log(`Arcjet: decision = ${decision.conclusion}`);
for (const result of decision.results) { this.logger.log("Rule Result", result);
if (result.reason.isRateLimit()) { this.logger.log("Rate limit rule", result); }
if (result.reason.isBot()) { this.logger.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}Token bucket request
Section titled “Token bucket request”When using a token bucket rule, pass an additional requested prop (a positive
integer) to the protect function. This is the number of tokens the client is
requesting to withdraw from the bucket.
import { ARCJET, type ArcjetNest, tokenBucket } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file, such as:// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ) .protect(req, { requested: 50 });
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}Rate limit headers
Section titled “Rate limit headers”With a rate limit rule enabled, you can access additional metadata in every Arcjet decision result:
max(number): The configured maximum number of requests applied to this request.remaining(number): The number of requests remaining beforemaxis reached within the window.window(number): The total amount of seconds in which requests are counted.reset(number): The remaining amount of seconds in the window.
These can be used to return RateLimit HTTP headers (draft
RFC) to
offer the client more detail.
In JavaScript, use setRateLimitHeaders
from @arcjet/decorate. In Python, use set_rate_limit_headers from the
arcjet package. Both write RateLimit and RateLimit-Policy headers from the
decision.
When several rate limit results are present, the tightest remaining budget is
advertised. If two policies share the same max, no headers are written.
To set the rate limit headers on the NestJS response you need to add the
passthrough option to the @Res() decorator in your controller method:
@Res({ passthrough: true }). For details, see the NestJS docs on the
library-specific
approach.
import { setRateLimitHeaders } from "@arcjet/decorate";import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req, Res,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file, such as:// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() // The passthrough option allows us to access the response object so we can // set the rate limit headers. See // https://docs.nestjs.com/controllers#library-specific-approach async index(@Req() req: Request, @Res({ passthrough: true }) res: Response) { const decision = await this.arcjet .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
// Set the rate limit headers on the response object setRateLimitHeaders(res, decision);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}This would result in draft RFC response headers similar to the following:
...< RateLimit: limit=10, remaining=5, reset=9< RateLimit-Policy: 10;w=10...Error handling
Section titled “Error handling”Arcjet is designed to fail open so that a service issue or misconfiguration does not block all requests. The SDK also times out and fails open after 2000 ms by default. However, in most cases, the response time is less than 20 ms to 30 ms.
If there is an error condition when processing the rule, Arcjet returns an
ERROR result for that rule and you can check the message property on the
rule’s error result for more information.
If all other rules that were run returned an ALLOW result, then the final
Arcjet conclusion is ERROR.
import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Logger, Req, Res,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file, such as:// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file, such as:// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { // Make use of the NestJS logger: https://docs.nestjs.com/techniques/logger // See // https://github.com/arcjet/example-nestjs/blob/ec742e58c8da52d0a399327182c79e3f4edc8f3b/src/app.module.ts#L29 // and https://github.com/arcjet/example-nestjs/blob/main/src/arcjet-logger.ts // for an example of how to connect Arcjet to the NestJS logger private readonly logger = new Logger(PageController.name);
constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
for (const { reason } of decision.results) { if (reason.isError()) { // Fail open by logging the error and continuing this.logger.error(`Arcjet error: ${reason.message}`); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}Testing
Section titled “Testing”Arcjet runs the same in any environment, including locally and in CI. You can
use the mode set to DRY_RUN to log the results of rule execution without
blocking any requests.
We have an example test framework you can use to automatically test your rules. Arcjet can also be triggered based using a sample of your traffic.
For details, see the Testing section of the docs.