# Rate limiting rules

Rate limiting rules block, challenge, or log clients exceeding a request threshold. Each rule defines: what traffic it matches, the counting characteristics (e.g. IP, JA3 fingerprint, colo), the period, the threshold, and the mitigation (block/challenge/log) with a timeout.

## Start in Log

The docs recommend deploying first with the **Log** action to validate the threshold against real traffic, then switching to block or challenge once confident. A threshold tuned from guesswork blocks legitimate users; the request-rate analysis tab shows the impact of a candidate limit on actual traffic before you deploy.

## The counting decisions

- **Characteristics**: counting by IP alone punishes NATed offices and mobile carriers (many users, one IP). Consider JA3/JA4 fingerprints or header-based keys (API keys) for APIs.
- **Cached assets**: by default you can choose whether cached responses count toward the rate. For origin protection, count only requests that reach the origin; for abuse prevention, count everything.
- **Counting expression**: can differ from the rule expression and can include response fields, so you can count e.g. only failed logins (response 401) toward a brute-force limit. This is the single most useful advanced feature: rate-limit the failure, not the endpoint.

## The failure modes

- Threshold too low on a login endpoint: real users get blocked during normal retry behavior. Log first.
- Lowering a threshold: add the new rule alongside the old one, wait out the old rule's action duration, then delete the old. Raising a threshold: edit in place.
- Forgetting that rate limits are per-datacenter characteristics plus key: test from realistic client distributions, not one laptop.

## Checklist

- Log, analyze, then enforce.
- Count failures (4xx/5xx via counting expression), not raw hits, for auth endpoints.
- Document the threshold rationale next to the rule; future you will not remember why 100/min.