Rate Limiting

BunBase includes built-in rate limiting to protect your API from abuse.

How limits work

Each limit is per-IP (or per-user for authenticated routes) per minute.

Without Redis (default)

Counters are tracked in each worker process independently. The effective cluster-wide budget for a single client is:

effective limit = configured limit × WORKER_COUNT

For example, RATE_LIMIT_AUTH=10 with 4 workers allows up to 40 login attempts per IP per minute across the cluster. Size your limits accordingly.

With Redis / Valkey (v0.12+)

When REDIS_URL or VALKEY_URL is set, rate limit counters are stored in Redis and shared across all workers and machines. The configured limit is the true cluster-wide limit regardless of worker count.

REDIS_URL=redis://localhost:6379
# or
VALKEY_URL=redis://localhost:6379

If Redis becomes unavailable, BunBase automatically falls back to per-worker in-memory counters.

Endpoint type	Key	Default
Unauthenticated reads	per-IP	200 req/min
Auth (login, register, refresh)	per-IP	10 req/min
Authenticated CRUD	per-user-ID	500 req/min
Admin API	per-IP	50 req/min
File uploads	per-user-ID	20 req/min

Configuration

Override via environment variables (applied at startup):

RATE_LIMIT_PUBLIC_READS=200
RATE_LIMIT_AUTH=10
RATE_LIMIT_AUTHENTICATED=500
RATE_LIMIT_ADMIN=50
RATE_LIMIT_FILE_UPLOAD=20

Or change at runtime — no restart needed — from Studio → Settings → Rate Limits. Runtime settings take effect immediately in the current worker and propagate to other workers within 60 s.

See Configuration for the full reference.

Response

When a rate limit is exceeded, BunBase responds with 429 Too Many Requests:

{ "error": "Rate limit exceeded. Try again later." }

The Retry-After header indicates how many seconds to wait.

Per-user limiting

Authenticated requests are rate-limited by user ID in addition to IP. This prevents a single user from consuming the full IP limit shared with other users behind a NAT or proxy.