Multi-Bucket Rate Limiting: Why One Number for the Whole API Is a Mistake

"Rate limit: 100 requests per minute" is the laziest sentence you can write in an API spec. A single number applied equally to every endpoint treats a GET that reads a cached row the same as a POST that invokes a local LLM with hundreds of milliseconds of latency. In this portfolio's backend the Bucket4j buckets are four, not one, and even with four well-designed buckets I still had a production incident where a low-priority endpoint drained a critical one's quota.

Four buckets, four different product decisions

Rate limiting is not an isolated technical problem, it is a product decision disguised as configuration. In the backend, RateLimitConfig defines four policies with distinct semantics, each for a specific business reason:

• Generic API: 120 requests/second, refill 2 tokens/s per IP. Generous, because it covers the vast majority of cheap endpoints (reading articles, tool catalog, search).
• AI: 6 requests/10 seconds, refill 1 token/10s per IP. An order of magnitude tighter, because every request invokes Ollama on-prem and consumes real compute on the same VPS that also serves application traffic.
• Analyzer report download: 30 requests/minute per IP, a dedicated bucket. Introduced after noticing that a report download gated only by a random UUIDv4 risked inheriting either the AI bucket (too tight, causing false 429s on legitimate downloads) or the API bucket (too loose, offering little protection against probing).
• Knowledge Pack download token: 5 tokens/hour, keyed by authenticated userId, not IP. The only one of the four buckets keyed by identity instead of network address.

Routing to the right bucket is where the bug is born

Having four buckets is not enough, every request also needs to be routed to the correct one, and this is where the code gets complicated fast. The backend classifies a path as "AI" not just by prefix (/api/v1/ai/**), but with an explicit list of fiscal paths that share the AI bucket because they call Ollama (/fiscal/regime/compare, /fiscal/chat, /business-tools/ai-boost, the sector analyzers, the trip planner), plus substring rules for dynamic ProjectHub paths (/project-hub/workspaces/{slug}/ai/*). Every time I add a new endpoint that calls Ollama, I have to remember to add it explicitly to this list, otherwise it falls into the generic 120-requests/second bucket and becomes an economic abuse vector on AI inference disguised as normal API traffic.

The reverse case, equally insidious, was the report download: it initially inherited the AI bucket by path-categorization mistake (shared prefix), with the result that legitimate users downloading their own report got 429s after a few attempts, because they consumed the same scarce quota reserved for Ollama calls. The fix (CR-01 in the code) explicitly excludes that path before even checking whether it starts with /api/v1/ai, and assigns it a dedicated 30/minute bucket, neither too tight nor too loose for the use case.

Postmortem: when the wrong bucket blocks the right endpoint

The most instructive production case was not intentional abuse, but legitimate browser behavior draining a shared resource. During the Content Security Policy rollout in Report-Only mode, every prerendered page loaded by the browser generated roughly 20 POST /csp-report requests per single page-load (expected CSP violations, not malicious). Those requests shared the same generic 120/s API bucket also used by the email-verification endpoint. The CSP-report flood exhausted the IP-scoped quota enough to trigger 429s on legitimate email-verification requests from the same client too. The fix was excluding /csp-report from the rate limiter entirely, because it is a browser telemetry endpoint, not an application endpoint, and it must never compete for the same quota as real user actions.

The general lesson, not specific to CSP: any endpoint the browser calls automatically, without an explicit user action (telemetry, beacons, reports), must be kept out of rate limiting shared with user-triggered endpoints, or isolated in its own dedicated bucket. If it shares the quota with a real user action, the browser's automatic volume always wins, and the real user pays the price for an error they did not cause.

Trade-off: IP-based versus identity-based

Three of the four buckets are keyed by IP, one by userId. IP-based keying has a known limit: behind shared corporate NAT or CGNAT mobile networks, many legitimate users can share the same IP and therefore the same bucket, increasing the risk of 429s on aggregated innocuous traffic. Identity-based (userId) keying requires prior authentication, so it cannot be used on public pre-login endpoints (login itself, or email verification). The practical choice in the backend was IP-based everywhere except where the endpoint already requires an authenticated user performing a high-value action (issuing a download token): there, identity is a more precise signal than IP and the added complexity is worth it.

When one generic bucket is genuinely enough

Not every backend needs four buckets. If there is no endpoint invoking an AI model or a server-side expensive operation, a single well-sized generic bucket is sufficient and multi-bucket routing complexity is unjustified. The real signal that differentiation is needed is the presence of endpoints with asymmetric compute or network cost relative to the rest of the API, not the absolute number of exposed endpoints.