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

Each rate limit is configured on an exact path with a set of client characteristics and algorithm specific options.

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.

JavaScript / TypeScript
Python

1
// Options for fixed window rate limit
2
// See https://docs.arcjet.com/rate-limiting/configuration
3
type FixedWindowRateLimitOptions = {
4
  // "LIVE" will block requests. "DRY_RUN" will log only
5
  mode?: "LIVE" | "DRY_RUN";
6
  // How the client is identified. See https://docs.arcjet.com/fingerprints
7
  characteristics?: string[];
8
  // Time window the rate limit applies to (e.g. "1h", "60s", or seconds as a number)
9
  window: string | number;
10
  // Maximum number of requests allowed in the time window
11
  max: number;
12
};

# Signature for arcjet.fixed_window
# See https://docs.arcjet.com/rate-limiting/configuration
def 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

import os

from arcjet import Mode, arcjet, fixed_window

aj = arcjet(
    key=os.environ["ARCJET_KEY"],
    rules=[
        fixed_window(
            mode=Mode.LIVE,  # Blocks requests. Use Mode.DRY_RUN to log only
            # Tracked by IP address by default, but this can be customized
            # See https://docs.arcjet.com/fingerprints
            # characteristics=["ip.src"],
            window=60,  # 60 second fixed window
            max=100,  # allow a maximum of 100 requests
        ),
    ],
)

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.

JavaScript / TypeScript
Python

1
// Options for sliding window rate limit
2
// See https://docs.arcjet.com/rate-limiting/configuration
3
type SlidingWindowRateLimitOptions = {
4
  // "LIVE" will block requests. "DRY_RUN" will log only
5
  mode?: "LIVE" | "DRY_RUN";
6
  // How the client is identified. See https://docs.arcjet.com/fingerprints
7
  characteristics?: string[];
8
  // The time interval in seconds for the rate limit
9
  interval: number;
10
  // Maximum number of requests allowed over the time interval
11
  max: number;
12
};

# Signature for arcjet.sliding_window
# See https://docs.arcjet.com/rate-limiting/configuration
def 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

import os

from arcjet import Mode, arcjet, sliding_window

aj = arcjet(
    key=os.environ["ARCJET_KEY"],
    rules=[
        sliding_window(
            mode=Mode.LIVE,  # Blocks requests. Use Mode.DRY_RUN to log only
            # Tracked by IP address by default, but this can be customized
            # See https://docs.arcjet.com/fingerprints
            # characteristics=["ip.src"],
            interval=60,  # 60 second sliding window
            max=100,  # allow a maximum of 100 requests
        ),
    ],
)

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.

JavaScript / TypeScript
Python

1
// Options for token bucket rate limit
2
// See https://docs.arcjet.com/rate-limiting/configuration
3
type TokenBucketRateLimitOptions = {
4
  // "LIVE" will block requests. "DRY_RUN" will log only
5
  mode?: "LIVE" | "DRY_RUN";
6
  // How the client is identified. See https://docs.arcjet.com/fingerprints
7
  characteristics?: string[];
8
  // Number of tokens to add to the bucket at each interval
9
  refillRate: number;
10
  // The interval in seconds to add tokens to the bucket
11
  interval: number;
12
  // The maximum number of tokens the bucket can hold
13
  capacity: number;
14
};

# Signature for arcjet.token_bucket
# See https://docs.arcjet.com/rate-limiting/configuration
def 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

For how to specify the number of tokens to request, see the token bucket request example.

import os

from arcjet import Mode, arcjet, token_bucket

aj = arcjet(
    key=os.environ["ARCJET_KEY"],
    rules=[
        token_bucket(
            mode=Mode.LIVE,  # Blocks requests. Use Mode.DRY_RUN to log only
            # Tracked by IP address by default, but this can be customized
            # See https://docs.arcjet.com/fingerprints
            # characteristics=["ip.src"],
            refill_rate=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.

JavaScript / TypeScript
Python

1
// Deduct 50 tokens from the bucket
2
// The value for `requested` must be a positive integer
3
const decision = await aj.protect(req, { requested: 50 });

# Deduct 50 tokens from the bucket
# The value for `requested` must be a positive integer
decision = await aj.protect(request, requested=50)  # use aj.protect(request, ...) for arcjet_sync

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 os

from arcjet import Mode, arcjet, fixed_window
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

aj = arcjet(
    key=os.environ["ARCJET_KEY"],  # Get your site key from https://console.arcjet.com
    rules=[
        fixed_window(
            mode=Mode.LIVE,
            characteristics=["userId"],
            window=3600,  # 1 hour in seconds
            max=60,
        ),
    ],
)


@app.get("/")
async def index(request: Request):
    # Pass userId as a string to identify the user. This could also be a number
    # or boolean value
    decision = await aj.protect(request, characteristics={"userId": "user123"})
    print("Arcjet decision", decision)

    if decision.is_denied():
        return JSONResponse({"error": "Too Many Requests"}, status_code=429)

    return {"message": "Hello world"}

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.

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.

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 with req_ for decisions involving the Arcjet cloud API. For decisions taken locally, the prefix is lreq_.
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 of ArcjetRuleResult objects 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:

JavaScript / TypeScript
Python

1
for (const result of decision.results) {
2
  console.log("Rule Result", result);
3
}

for result in decision.results:
    print("Rule Result", result)

This example logs the full result as well as each rate limit rule:

import logging
import os

from arcjet import Mode, arcjet, detect_bot, fixed_window
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

logger = logging.getLogger(__name__)

aj = arcjet(
    key=os.environ["ARCJET_KEY"],  # Get your site key from https://console.arcjet.com
    rules=[
        fixed_window(mode=Mode.LIVE, window=3600, max=60),
        detect_bot(
            mode=Mode.LIVE,
            allow=[],  # "allow none" will block all detected bots
        ),
    ],
)


@app.get("/")
async def index(request: Request):
    decision = await aj.protect(request)

    for result in decision.results:
        logger.info("Rule Result %s", result)

        if result.reason_v2.type == "RATE_LIMIT":
            logger.info("Rate limit rule %s", result)

        if result.reason_v2.type == "BOT":
            logger.info("Bot protection rule %s", result)

    if decision.is_denied():
        if decision.reason_v2.type == "RATE_LIMIT":
            return JSONResponse({"error": "Too Many Requests"}, status_code=429)
        return JSONResponse({"error": "Forbidden"}, status_code=403)

    return {"message": "Hello world"}

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 os

from arcjet import Mode, arcjet, token_bucket
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

aj = arcjet(
    key=os.environ["ARCJET_KEY"],  # Get your site key from https://console.arcjet.com
    rules=[
        token_bucket(
            mode=Mode.LIVE,
            # Tracked by IP address by default, but this can be customized
            # See https://docs.arcjet.com/fingerprints
            # characteristics=["ip.src"],
            refill_rate=40_000,
            interval=86_400,  # 1 day in seconds
            capacity=40_000,
        ),
    ],
)


@app.get("/")
async def index(request: Request):
    decision = await aj.protect(request, requested=50)
    print("Arcjet decision", decision)

    if decision.is_denied():
        return JSONResponse({"error": "Too Many Requests"}, status_code=429)

    return {"message": "Hello world"}

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 before max is 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.

import os

from arcjet import Mode, arcjet, fixed_window, set_rate_limit_headers
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

aj = arcjet(
    key=os.environ["ARCJET_KEY"],  # Get your site key from https://console.arcjet.com
    rules=[
        fixed_window(
            mode=Mode.LIVE,
            window=3600,
            max=60,
        ),
    ],
)


@app.get("/")
async def index(request: Request):
    decision = await aj.protect(request)
    print("Arcjet decision", decision)

    if decision.is_denied():
        response = JSONResponse(
            {"error": "Too Many Requests", "reason": str(decision.reason_v2)},
            status_code=429,
        )
        set_rate_limit_headers(response, decision)
        return response

    response = JSONResponse({"message": "Hello world"})
    set_rate_limit_headers(response, decision)
    return response

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

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 logging
import os

from arcjet import Mode, arcjet, token_bucket
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

logger = logging.getLogger(__name__)

aj = arcjet(
    key=os.environ["ARCJET_KEY"],  # Get your site key from https://console.arcjet.com
    rules=[
        # Create a token bucket rate limit. Other algorithms are supported.
        token_bucket(
            mode=Mode.LIVE,  # Blocks requests. Use Mode.DRY_RUN to log only
            characteristics=["userId"],  # track requests by a custom user ID
            refill_rate=5,  # refill 5 tokens per interval
            interval=10,  # refill every 10 seconds
            capacity=10,  # bucket maximum capacity of 10 tokens
        ),
    ],
)


@app.get("/")
async def index(request: Request):
    user_id = "user123"  # Replace with your authenticated user ID
    decision = await aj.protect(
        request, characteristics={"userId": user_id}, requested=5
    )
    print("Arcjet decision", decision)

    for result in decision.results:
        if result.reason_v2.type == "ERROR":
            # Fail open by logging the error and continuing
            logger.warning("Arcjet error: %s", result.reason_v2.message)
            # You could also fail closed here for very sensitive routes:
            # return JSONResponse({"error": "Service unavailable"}, status_code=503)

    if decision.is_denied():
        return JSONResponse({"error": "Too Many Requests"}, status_code=429)

    return {"message": "Hello world"}

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.