Rate limiting

Overview

Rate limiting means OpenQuok counts how many requests someone sends in a time window. A request can be from a signed-in user, an API key, or a visitor IP address.

When the count goes over the cap, the API returns 429 Too Many Requests. The person must wait until the window resets.

Limits protect sign-in, the dashboard, public blog and listing pages, uploads, and integrations. Messages from social networks (webhooks) are not rate limited. Those go server to server.

The table below shows typical production caps. You can change them with environment variables (see Environment variables).

Limits by area

Each row is one rule. One request matches one rule, not every rule at once.

Public read pages are not unlimited. The first row stops heavy scraping from overloading your server.

Visitor IP address

The API needs each visitor’s real IP to count fairly.

If Cloudflare sits in front of OpenQuok, set TRUST_CLOUDFLARE_HEADERS so the API sees the visitor IP, not one shared edge IP. Without that, many real users can look like one person and hit limits too soon.

Optional VERIFY_CLOUDFLARE_IP_RANGE only trusts that header when the request really came through Cloudflare.

Shared counters with Redis

In production, counters usually live in Redis when RATE_LIMIT_REDIS_ENABLED is on. Then every API server shares the same counts.

Redis uses the same host settings as cache (REDIS_HOST, REDIS_PORT). If Redis is off or unreachable at startup, each API instance keeps its own in-memory counts until Redis is available.

Public content cache (related)

Public read routes also send cache headers. Browsers and CDNs can reuse responses for a short time. That lowers load and helps you stay under read limits.

The public website follows similar rules. For why more than one cache layer exists, see Cache design → Public content and caching.

Tune cache duration with PUBLIC_CMS_CACHE_ENABLED and PUBLIC_CMS_CACHE_*.

When something is blocked

Search API logs for Rate limit exceeded. Each line shows which rule fired, the IP, the path, and the cap.

If real users hit limits, raise the cap for that area (public read or signed-in session). Lower caps only when you see abuse.

Environment variables

Set RATE_LIMIT_ENABLED to false to turn off all limiters. Do not do this in production.

Copy backend/.env.development.example to backend/.env.development.local for sample values when you test locally:

# From repo root — example only; adjust values for your machine
cp backend/.env.development.example backend/.env.development.local

Example production-related values (full list is in the example env file):

RATE_LIMIT_ENABLED=true
RATE_LIMIT_REDIS_ENABLED=true
TRUST_CLOUDFLARE_HEADERS=true
PUBLIC_READ_RATE_LIMIT_MAX=600
SESSION_RATE_LIMIT_MAX=2000

Production checklist

Workers and the web app do not need these variables. See Production deployment.

Related