Rate Limiting

Brume Limit is a rate-limiting gateway: you define rules, evaluate requests against them with a single HTTP call, and read the standard X-RateLimit-* response headers. Every evaluation runs as one atomic Lua script against a dedicated Redis — no race windows, no double-counting, nothing for you to operate.

Rules

A rule binds five things:

Optional fields: cost (default cost per request, 1–10,000), and for token bucket, burst (burst ceiling, defaults to limit) and refill_rate (tokens/second, defaults to limit / window_seconds).

Create, update, list, and delete rules under /v1/ratelimit/rules.

The four algorithms

Pick token bucket for smooth APIs with occasional bursts, fixed window for simple predictable resets, sliding window log where exactness matters, and sliding window counter for high-volume rolling rates.

limit vs check

POST /v1/ratelimit/limit consumes capacity. POST /v1/ratelimit/check is read-only — it always evaluates with cost 0 and never moves a counter. Use check to show "remaining" state in a UI without spending the user's budget.

// Consume one unit for this request.
const verdict = await limit.limit('api', user.id);

// Read state without consuming (e.g. for a dashboard).
const state = await limit.check('api', user.id);

Both accept an optional cost to consume more than one unit (an expensive search might cost 5), and an optional explicit identifier. When the identifier is omitted it is derived server-side from the rule's identifier_type — client IP, API key, or route.

Multi-rule evaluation

Evaluate several existing rules in one call with limitMulti / checkMulti. Each entry references a rule by namespace; the response is the most restrictive result across all rules:

const result = await limit.limitMulti({
  namespace: 'api',
  identifier: user.id,
  rules: [{ namespace: 'api-daily' }],
});

Here the request is evaluated against both the api rule (per-minute) and the api-daily rule (per-day) in a single round trip, and denied if either denies.

Response shape

Evaluations always return HTTP 200 with a JSON body:

{
  "success": true,
  "limit": 100,
  "remaining": 42,
  "reset": 1756339200000,
  "retry_after": null,
  "window": "sliding_window_counter",
  "degraded": false
}

success: false means over the limit. retry_after (seconds) is present only on denial. degraded: true means the rate-limit Redis was unreachable and the request was allowed via fail-open — see Error Handling.

Reading status

GET /v1/ratelimit/status/:namespace returns the rule plus a read-only usage evaluation for the caller's identifier — useful for "you have N requests left" UIs.

Beyond the rule

• Overrides — give one identifier a different limit without a second rule
• Quotas — long-window daily/weekly/monthly budgets enforced alongside the rate rule
• Blocklists — deny or admit identifiers before any rule runs
• Analytics — per-identifier allowed/denied/cost for a namespace and time range

Overrides, quotas, and blocklists are managed in the dashboard and enforced inside the same atomic evaluation.

Analytics

GET /v1/ratelimit/analytics?namespace=api&from=...&to=... returns the top identifiers by request count in a time window, each with allowed, denied, and cost totals, plus aggregate totals for the window. from and to accept epoch milliseconds or ISO 8601. Use it to find the client hammering a namespace without adding counters to your own code — the dashboard's Analytics tab renders the same data as a table.

{
  "identifiers": [
    { "identifier": "user_9f2", "allowed": 4120, "denied": 88, "cost": 4208 }
  ],
  "totals": { "allowed": 121540, "denied": 902, "cost": 122442 },
  "degraded": false
}

degraded: true means the analytics store was unreachable and empty data was returned. Analytics requires the API key's read_stats scope.