docs: clarify rate limit fingerprint behavior

public/llms-full.txt

@@ -1442,6 +1442,14 @@ Parameters:
 Python: `sliding_window(mode=Mode.LIVE, interval=60, max=100)` — `interval`
 takes seconds as a number.
 
+Rate-limit characteristics are combined into one fingerprint. For example,
+`["ip.src", "userId"]` creates one bucket for each unique IP/user pair, not
+separate IP and user counters. Configure separate rate-limit rules when you
+need independent limits, such as one rule keyed by `userId` for an account
+quota and another keyed by `ip.src` for per-IP throttling. IP-based limits are
+useful for anonymous traffic, but IP addresses can be shared or rotated; use a
+stable user, account, tenant, or API key for authenticated traffic.
+
 ### sensitiveInfo(options)
 
 Detects and blocks requests containing sensitive information (PII).

src/content/docs/fingerprints.mdx

@@ -30,6 +30,13 @@ instance.
 Built-in options are managed by the SDK and are always available. If multiple
 options are provided, they will be combined.
 
+Combining characteristics creates one fingerprint from the full set of values.
+For example, `["ip.src", "http.request.headers[\"x-api-key\"]"]` identifies
+each unique IP address and API key pair. This is useful when you want a limit or
+decision cache per combination, but it does not create separate counters for
+each characteristic. To enforce independent limits, configure separate rules
+with the characteristics you want each rule to track.
+
 :::caution
 If you specify different characteristics and do not include `ip.src`, you may
 inadvertently generate the same fingerprint for multiple users.

src/content/docs/rate-limiting/index.mdx

@@ -125,6 +125,43 @@ that align with your concept of a “user”. For example:
 - IP + API key (per-client limits),
 - User ID or authentication token (per-account limits).
 
+Multiple characteristics are combined into a single fingerprint. For example,
+`["ip.src", "userId"]` creates one rate-limit bucket for each unique IP address
+and user ID pair. It does not create separate IP and user ID counters.
+
+If you need independent limits, configure separate rate-limit rules. For
+example, an authenticated API route might use one rule keyed by `userId` to
+enforce a per-account quota, and another rule keyed by `ip.src` to throttle
+traffic from any single IP address:
+
+```ts
+import arcjet, { fixedWindow } from "@arcjet/next";
+
+const aj = arcjet({
+  key: process.env.ARCJET_KEY!,
+  rules: [
+    fixedWindow({
+      characteristics: ["userId"],
+      mode: "LIVE",
+      window: "60s",
+      max: 100,
+    }),
+    fixedWindow({
+      characteristics: ["ip.src"],
+      mode: "LIVE",
+      window: "60s",
+      max: 20,
+    }),
+  ],
+});
+```
+
+IP-based limits are useful for anonymous traffic and broad abuse throttles, but
+IP addresses can be shared by many users or changed by an attacker. For
+authenticated traffic, prefer a stable application identifier such as a user ID,
+account ID, tenant ID, or API key, and add a separate IP-based rule only when
+you also want per-IP throttling.
+
 Matching fingerprints to the right identifiers is critical to applying rate
 limits fairly and avoiding unintended blocking.
 

tests/llms-txt.test.ts-snapshots/llms-full-chromium-darwin.md

@@ -1442,6 +1442,14 @@ Parameters:
 Python: `sliding_window(mode=Mode.LIVE, interval=60, max=100)` — `interval`
 takes seconds as a number.
 
+Rate-limit characteristics are combined into one fingerprint. For example,
+`["ip.src", "userId"]` creates one bucket for each unique IP/user pair, not
+separate IP and user counters. Configure separate rate-limit rules when you
+need independent limits, such as one rule keyed by `userId` for an account
+quota and another keyed by `ip.src` for per-IP throttling. IP-based limits are
+useful for anonymous traffic, but IP addresses can be shared or rotated; use a
+stable user, account, tenant, or API key for authenticated traffic.
+
 ### sensitiveInfo(options)
 
 Detects and blocks requests containing sensitive information (PII).

tests/llms-txt.test.ts-snapshots/llms-full-chromium-linux.md

@@ -1442,6 +1442,14 @@ Parameters:
 Python: `sliding_window(mode=Mode.LIVE, interval=60, max=100)` — `interval`
 takes seconds as a number.
 
+Rate-limit characteristics are combined into one fingerprint. For example,
+`["ip.src", "userId"]` creates one bucket for each unique IP/user pair, not
+separate IP and user counters. Configure separate rate-limit rules when you
+need independent limits, such as one rule keyed by `userId` for an account
+quota and another keyed by `ip.src` for per-IP throttling. IP-based limits are
+useful for anonymous traffic, but IP addresses can be shared or rotated; use a
+stable user, account, tenant, or API key for authenticated traffic.
+
 ### sensitiveInfo(options)
 
 Detects and blocks requests containing sensitive information (PII).

tests/llms-txt.test.ts-snapshots/rate-limiting-chromium-darwin.md

@@ -68,6 +68,17 @@ To ensure rate limits are applied correctly, choose fingerprint characteristics
 *   IP + API key (per-client limits),
 *   User ID or authentication token (per-account limits).
 
+Multiple characteristics are combined into a single fingerprint. For example, `["ip.src", "userId"]` creates one rate-limit bucket for each unique IP address and user ID pair. It does not create separate IP and user ID counters.
+
+If you need independent limits, configure separate rate-limit rules. For example, an authenticated API route might use one rule keyed by `userId` to enforce a per-account quota, and another rule keyed by `ip.src` to throttle traffic from any single IP address:
+
+```
+1import arcjet, { fixedWindow } from "@arcjet/next";2
+3const aj = arcjet({4  key: process.env.ARCJET_KEY!,5  rules: [6    fixedWindow({7      characteristics: ["userId"],8      mode: "LIVE",9      window: "60s",10      max: 100,11    }),12    fixedWindow({13      characteristics: ["ip.src"],14      mode: "LIVE",15      window: "60s",16      max: 20,17    }),18  ],19});
+```
+
+IP-based limits are useful for anonymous traffic and broad abuse throttles, but IP addresses can be shared by many users or changed by an attacker. For authenticated traffic, prefer a stable application identifier such as a user ID, account ID, tenant ID, or API key, and add a separate IP-based rule only when you also want per-IP throttling.
+
 Matching fingerprints to the right identifiers is critical to applying rate limits fairly and avoiding unintended blocking.
 
 Discussion

tests/llms-txt.test.ts-snapshots/rate-limiting-chromium-linux.md

@@ -68,6 +68,17 @@ To ensure rate limits are applied correctly, choose fingerprint characteristics
 *   IP + API key (per-client limits),
 *   User ID or authentication token (per-account limits).
 
+Multiple characteristics are combined into a single fingerprint. For example, `["ip.src", "userId"]` creates one rate-limit bucket for each unique IP address and user ID pair. It does not create separate IP and user ID counters.
+
+If you need independent limits, configure separate rate-limit rules. For example, an authenticated API route might use one rule keyed by `userId` to enforce a per-account quota, and another rule keyed by `ip.src` to throttle traffic from any single IP address:
+
+```
+1import arcjet, { fixedWindow } from "@arcjet/next";2
+3const aj = arcjet({4  key: process.env.ARCJET_KEY!,5  rules: [6    fixedWindow({7      characteristics: ["userId"],8      mode: "LIVE",9      window: "60s",10      max: 100,11    }),12    fixedWindow({13      characteristics: ["ip.src"],14      mode: "LIVE",15      window: "60s",16      max: 20,17    }),18  ],19});
+```
+
+IP-based limits are useful for anonymous traffic and broad abuse throttles, but IP addresses can be shared by many users or changed by an attacker. For authenticated traffic, prefer a stable application identifier such as a user ID, account ID, tenant ID, or API key, and add a separate IP-based rule only when you also want per-IP throttling.
+
 Matching fingerprints to the right identifiers is critical to applying rate limits fairly and avoiding unintended blocking.
 
 Discussion