Arcjet rate limiting allows you to define rules which limit the number of
requests a client can make over a period of time.
Configuration options
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. See the fixed window algorithm
description for more details about how
the algorithm works.
Fixed window example
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. See the sliding
window algorithm description for more
details about how the algorithm works.
Sliding window example
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. See the token bucket algorithm
description for more details about how
the algorithm works.
Token bucket example
See the token bucket example for how to specify the
number of tokens to request.
Identifying 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.
The arcjet client is configured with one or more rules which take one or many
of the above options.
Example - single rate limit
Set a single rate limit rule on the /api/hello API route that applies a 60
request limit per hour per IP address (the default if no characteristics are
specified).
Example - dry run mode for new rules
Rate limits can be combined in the arcjet client which allows you to test new
configurations in dry run mode first before enabling them in live mode. You can
inspect the results of each rule by logging them or using the Arcjet
Dashboard.
Decision
Arcjet provides a single protect function that is used to execute your
protection rules. This requires a request argument which is the request
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. See IP analysis in the
SDK reference for more information.
When using a token bucket rule, an additional requested prop should be passed
to the protect function. This is the number of tokens the client is requesting
to withdraw from the bucket.
Arcjet is designed to fail open so that a service issue or misconfiguration does
not block all requests. The SDK will also time out and fail open after 500ms
when ARCJET_ENV is "production" and 1000ms otherwise. However, in most cases,
the response time will be less than 20-30ms.
If there is an error condition, Arcjet will return an ERRORconclusion.
The example below shows how to configure a rate limit on a single API route. It
applies a limit of 60 requests per hour per IP address. If the limit is
exceeded, the client is blocked for 10 minutes before being able to make any
further requests.
Applying a rate limit by IP address is the default if no
characteristics are specified.
APIs are commonly protected by keys. You may wish to apply a rate limit based on
the key, regardless of which IPs the requests come from. To achieve this, you
can specify the characteristics Arcjet will use to track the limit.
The example below shows how to configure a rate limit on a single API route. It
applies a limit of 60 requests per hour per API key, where the key is provided
in a custom header called x-api-key. If the limit is exceeded, the client is
blocked for 10 minutes before being able to make any further requests.