docs
Concepts
Namespaces, identifiers, algorithms and cost.
Namespaces
A namespace is one limit policy, declared in code with lymit.namespace(name, config). Typical names: ai_generation, api, search, exports. Every namespace has its own counters, so a user can be over their AI budget and still search.
Identifiers
The string you pass to limit(). It is whatever your business logic keys on:
user_123— per-user limitsworkspace_42— shared team budgetstier:pro— one bucket for everyone on a tier (a shared pool)- an email, an API key id, an IP if you must
Identifiers are 1–256 characters. Each (namespace, identifier) pair has independent state.
Algorithms
| Algorithm | Config | Behaviour |
|---|---|---|
fixedWindow | { limit, window } | Up to limit cost per window aligned to the clock ("1m" → :00, :01, …). Simple; can admit up to 2× limit across a boundary. |
slidingWindow | { limit, window } | Smooths the boundary by weighting the previous window. Use when bursts at boundaries matter. |
tokenBucket | { capacity, refillRate, interval } | A bucket holding capacity tokens that refills continuously by refillRate every interval. Each call deducts cost — all or nothing. The algorithm for AI budgets. Pro plan. |
Durations are milliseconds or "500ms", "30s", "10m", "1h", "1d".
Cost
limit(identifier, { cost }) deducts cost units (default 1). For LLM calls, estimate the prompt tokens before calling the model and pass that; when the response arrives you know the exact total and can call limit again with the difference (or over-estimate up front). A call whose cost exceeds what is available deducts nothing.
cost: 0 peeks — it reports the current state without consuming.
Responses
| Field | Meaning |
|---|---|
success | Whether the request is allowed |
limit | The ceiling: window limit or bucket capacity, after any dashboard override |
remaining | Whole units still available |
reset | Unix ms. Windows: end of the current window. Token bucket: when full again (after success) or when cost becomes affordable (after rejection) |
retryAfter | ms until a retry can succeed. Absent on success, and absent when waiting cannot help (cost > capacity) |
Overrides
On Pro and Enterprise the dashboard can layer config over what your code declares: a workspace override for a whole namespace, and rules for single identifiers ("this VIP gets 50 000 tokens", "this scraper gets 2 per minute"). They take effect within seconds and never require a deploy. Raising a bucket's capacity does not top it up; use reset on the namespace page to grant a fresh allowance immediately.