Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Rate limiting expertise covering token bucket, sliding window, fixed window, and leaky bucket algorithms, distributed rate limiting, API quota management, graceful degradation, client-friendly responses, and production implementation patterns.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
533 lines · 2,321 words
You are an expert in designing and implementing rate limiting systems. Rate limiting protects your services from abuse, ensures fair resource allocation, and maintains system stability under load. The art is not just blocking requests, but doing it gracefully: clear error messages, appropriate headers, tiered limits, and degradation strategies that keep the system useful even when constrained.
| Threat |
|---|
Rate limiting expertise covering token bucket, sliding window, fixed window, and leaky bucket algorithms, distributed rate limiting, API quota management, graceful degradation, client-friendly responses, and production implementation patterns.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Rate Limiter Designer skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an expert in designing and implementing rate limiting systems. Rate limiting protects your services from abuse, ensures fair resource allocation, and maintains system stability under load. The art is not just blocking requests, but doing it gracefully: clear error messages, appropriate headers, tiered limits, and degradation strategies that keep the system useful even when constrained.
What it covers
Why Rate Limit
Algorithm Selection
Distributed Rate Limiting
API Quota Management
HTTP Response Standards
Graceful Degradation
Common Anti-Patterns
Rate Limiter Design Checklist
When to Use
Output Format
Example
Edge Cases
| With Rate Limiting |
|---|
| DDoS attack | Service overwhelmed, all users affected | Attack absorbed, legitimate traffic served |
| Misbehaving client | One client consumes all resources | Client throttled, others unaffected |
| Bug causing retry storm | Cascading failure across services | Retry storms contained |
| Expensive API abuse | Cost explosion (AI/ML endpoints) | Costs predictable and bounded |
| Data scraping | Entire database exfiltrated | Scraping slowed to impractical speed |
| Algorithm | Accuracy | Memory | Burst Handling | Complexity | Best For |
|---|---|---|---|---|---|
| Fixed Window | Low (boundary burst) | Very Low | Poor | Simple | Basic protection |
| Sliding Window Log | High | High | Good | Medium | Small-scale precision |
| Sliding Window Counter | Good | Low | Good | Medium | Most applications |
| Token Bucket | Good | Low | Controlled burst | Medium | APIs with burst allowance |
| Leaky Bucket | High | Low | No burst (smoothed) | Medium | Steady rate enforcement |
Window: 1 minute, Limit: 100 requests
Timeline:
00:00 ----------- 01:00 ----------- 02:00
[ Window 1 ] [ Window 2 ]
Problem: 100 requests at 00:50 + 100 requests at 01:10
= 200 requests in 20 seconds (2x the intended rate)
This "boundary burst" is the main drawback.class FixedWindowLimiter {
private counts = new Map<string, { count: number; resetAt: number }>();
isAllowed(key: string, limit: number, windowMs: number): boolean {
const now = Date.now();
const window = this.counts.get(key);
if (!window || now > window.resetAt) {
this.counts.set(key, { count: 1, resetAt: now + windowMs });
return true;
}
if (window.count < limit) {
window.count++;
return true;
}
return false;
}
}Combines two fixed windows with a weighted average. Solves the boundary burst problem with minimal memory.
class SlidingWindowLimiter {
// Uses weighted average of current and previous window
isAllowed(key: string, limit: number, windowMs: number): boolean {
const now = Date.now();
const currentWindow = Math.floor(now / windowMs);
const previousWindow = currentWindow - 1;
const currentCount = this.getCount(key, currentWindow);
const previousCount = this.getCount(key, previousWindow);
// Weight: how far into current window we are
const elapsed = now - currentWindow * windowMs;
const weight = elapsed / windowMs;
// Weighted count: full current window + fraction of previous
const estimatedCount = previousCount * (1 - weight) + currentCount;
if (estimatedCount < limit) {
this.incrementCount(key, currentWindow);
return true;
}
return false;
}
}Allows controlled bursts. Tokens accumulate at a fixed rate and are consumed per request.
PARAMETERS:
bucket_size: 10 (maximum burst size)
refill_rate: 5/sec (steady-state rate)
EXAMPLE:
t=0.0: Bucket has 10 tokens (full)
t=0.0: 8 requests arrive, consume 8 tokens. Bucket: 2
t=0.2: 1 token added (5/sec * 0.2s). Bucket: 3
t=0.5: 1.5 tokens added. Bucket: 4.5
t=1.0: 2.5 tokens added. Bucket: 7 (capped at 10)class TokenBucketLimiter {
private buckets = new Map<string, { tokens: number; lastRefill: number }>();
isAllowed(
key: string,
bucketSize: number,
refillRate: number, // tokens per second
tokensRequired: number = 1
): boolean {
const now = Date.now() / 1000;
let bucket = this.buckets.get(key);
if (!bucket) {
bucket = { tokens: bucketSize, lastRefill: now };
this.buckets.set(key, bucket);
}
// Refill tokens based on elapsed time
const elapsed = now - bucket.lastRefill;
bucket.tokens = Math.min(bucketSize, bucket.tokens + elapsed * refillRate);
bucket.lastRefill = now;
// Check if enough tokens
if (bucket.tokens >= tokensRequired) {
bucket.tokens -= tokensRequired;
return true;
}
return false;
}
}Processes requests at a fixed rate, smoothing out bursts. Excess requests queue up or are rejected.
VISUALIZATION:
+----------+
IN -> | Bucket | (queue of pending requests)
| (max 20) |
+----+-----+
| leak rate: 10 req/sec
v
Processing
If bucket is full and new request arrives -> REJECT (429)
Requests "leak out" at a steady rateSingle-node rate limiting breaks when you have multiple API servers. Redis provides atomic operations for distributed counting.
// Sliding window counter in Redis using Lua scripting for atomicity
const slidingWindowScript = `
local key = KEYS[1]
local window = tonumber(ARGV[1])
local limit = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
-- Remove expired entries
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
-- Count current entries
local count = redis.call('ZCARD', key)
if count < limit then
-- Add current request with timestamp as score
redis.call('ZADD', key, now, now .. '-' .. math.random(1000000))
redis.call('EXPIRE', key, window / 1000)
return 1 -- allowed
else
return 0 -- rejected
end
`;
class RedisRateLimiter {
constructor(private redis: Redis) {}
async isAllowed(key: string, limit: number, windowMs: number): Promise<{
allowed: boolean;
remaining: number;
retryAfter?: number;
}> {
const now = Date.now();
// Execute the Lua script atomically on Redis
const result = await this.redis.executeScript(
slidingWindowScript, 1, key, windowMs, limit, now
);
if (result === 1) {
const count = await this.redis.zcard(key);
return { allowed: true, remaining: limit - count };
}
// Calculate retry-after from oldest entry in window
const oldest = await this.redis.zrange(key, 0, 0, 'WITHSCORES');
const retryAfter = oldest.length > 1
? Math.ceil((parseInt(oldest[1]) + windowMs - now) / 1000)
: 1;
return { allowed: false, remaining: 0, retryAfter };
}
}-- Redis Lua script for distributed token bucket
local key = KEYS[1]
local bucket_size = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2]) -- tokens per second
local now = tonumber(ARGV[3]) -- current time in seconds
local requested = tonumber(ARGV[4]) -- tokens requested
-- Get current bucket state
local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
local tokens = tonumber(bucket[1]) or bucket_size
local last_refill = tonumber(bucket[2]) or now
-- Refill tokens
local elapsed = math.max(0, now - last_refill)
tokens = math.min(bucket_size, tokens + elapsed * refill_rate)
-- Check and consume
if tokens >= requested then
tokens = tokens - requested
redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
redis.call('EXPIRE', key, math.ceil(bucket_size / refill_rate) * 2)
return {1, math.floor(tokens)} -- allowed, remaining
else
redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
local wait_seconds = math.ceil((requested - tokens) / refill_rate)
return {0, 0, wait_seconds} -- rejected, remaining, retry_after
endinterface RateLimitTier {
name: string;
limits: {
perSecond: number;
perMinute: number;
perDay: number;
};
costMultiplier: Record<string, number>; // Endpoint-specific costs
}
const tiers: Record<string, RateLimitTier> = {
free: {
name: 'Free',
limits: { perSecond: 1, perMinute: 30, perDay: 1000 },
costMultiplier: { '/api/search': 1, '/api/generate': 10 },
},
pro: {
name: 'Pro',
limits: { perSecond: 10, perMinute: 300, perDay: 50000 },
costMultiplier: { '/api/search': 1, '/api/generate': 5 },
},
enterprise: {
name: 'Enterprise',
limits: { perSecond: 100, perMinute: 5000, perDay: 1000000 },
costMultiplier: { '/api/search': 1, '/api/generate': 1 },
},
};Apply limits at multiple granularities simultaneously:
async function checkRateLimits(apiKey: string, endpoint: string): Promise<RateLimitResult> {
const tier = await getTierForApiKey(apiKey);
const cost = tier.costMultiplier[endpoint] || 1;
// Check all levels (fail fast: cheapest check first)
const checks = [
{ key: `rl:${apiKey}:sec`, limit: tier.limits.perSecond, window: 1000 },
{ key: `rl:${apiKey}:min`, limit: tier.limits.perMinute, window: 60000 },
{ key: `rl:${apiKey}:day`, limit: tier.limits.perDay, window: 86400000 },
{ key: `rl:global:sec`, limit: 10000, window: 1000 },
];
for (const check of checks) {
const result = await limiter.isAllowed(check.key, check.limit, check.window);
if (!result.allowed) {
return {
allowed: false,
limit: check.limit,
window: check.window,
retryAfter: result.retryAfter,
};
}
}
return { allowed: true, remaining: checks[0].limit - cost };
}HTTP/1.1 200 OK
RateLimit-Limit: 100
RateLimit-Remaining: 42
RateLimit-Reset: 1640000000
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1640000000
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. You are allowed 100 requests per minute.",
"retryAfter": 30,
"limit": 100,
"window": "1m",
"documentation": "[reference URL]"
}
}import { Request, Response, NextFunction } from 'express';
function rateLimitMiddleware(limiter: RedisRateLimiter) {
return async (req: Request, res: Response, next: NextFunction) => {
const key = extractKey(req); // API key, user ID, or IP
const tier = await getTier(key);
const result = await limiter.isAllowed(
`rl:${key}:min`,
tier.limits.perMinute,
60000
);
// Always set headers (even when allowed)
res.set('RateLimit-Limit', String(tier.limits.perMinute));
res.set('RateLimit-Remaining', String(result.remaining));
res.set('RateLimit-Reset', String(Math.ceil(Date.now() / 1000) + 60));
if (!result.allowed) {
res.set('Retry-After', String(result.retryAfter));
return res.status(429).json({
error: {
code: 'RATE_LIMIT_EXCEEDED',
message: `Rate limit exceeded. Limit: ${tier.limits.perMinute} requests per minute.`,
retryAfter: result.retryAfter,
},
});
}
next();
};
}UNDER HEAVY LOAD, DEGRADE GRACEFULLY:
Tier 0 (Normal): All features available
Tier 1 (Elevated): Disable expensive endpoints (search, reports)
Reduce rate limits by 50%
Tier 2 (High): Serve cached responses for read endpoints
Disable all write endpoints except critical ones
Tier 3 (Critical): Static error page
Only health checks respond
IMPLEMENTATION:
- Monitor system load (CPU, memory, queue depth, error rate)
- Automatically adjust tier based on thresholds
- Each tier has predefined behavior for each endpoint// Return helpful information to clients
function buildRateLimitResponse(result: RateLimitResult, tier: Tier) {
return {
error: {
code: 'RATE_LIMIT_EXCEEDED',
message: `You have exceeded your ${tier.name} plan limit.`,
retryAfter: result.retryAfter,
currentUsage: {
used: result.limit - result.remaining,
limit: result.limit,
window: '1 minute',
resetsAt: new Date(result.resetAt).toISOString(),
},
upgrade: tier.name !== 'enterprise' ? {
message: `Upgrade to ${nextTier(tier).name} for higher limits.`,
url: '[reference URL]',
} : undefined,
},
};
}Rate limiting by IP only: NATs and VPNs share IPs. Thousands of legitimate users behind one corporate NAT get blocked together. Use API keys or user IDs as the primary key, IP as fallback.
No rate limit headers: Clients have no way to know their limit or remaining quota. They cannot implement backoff without trial and error. Always send headers.
Hard cutoff with no warning: Going from "allowed" to "blocked" instantly. Provide RateLimit-Remaining headers so clients can slow down before hitting the limit.
Same limits for all endpoints: A search endpoint costs 100x more than a health check. Weight expensive endpoints higher or set per-endpoint limits.
Rate limiting only at the edge: If an internal service calls another internal service in a retry loop, there is no protection. Apply rate limiting at service boundaries too.
Not rate limiting yourself: Your own background jobs and internal tools can overwhelm your services. Rate limit internal callers too, especially batch processors.
Algorithm selected based on requirements (burst tolerance, accuracy, memory)
Distributed implementation using Redis or equivalent
Rate limit key strategy defined (API key > user ID > IP)
Tiered limits defined per plan/subscription level
Per-endpoint weighting for expensive operations
Standard HTTP headers returned (RateLimit-Limit, Remaining, Reset)
429 responses include Retry-After and helpful error message
Graceful degradation tiers defined for overload scenarios
Global rate limit protects against complete system overload
Internal service-to-service rate limiting implemented
Monitoring: track rate limit hits, rejections, and degradation tier
Client documentation explains limits, headers, and best practices
Use this skill when:
Designing or implementing rate limiter designer solutions
Reviewing or improving existing rate limiter designer approaches
Making architectural or implementation decisions about rate limiter designer
Learning rate limiter designer patterns and best practices
Troubleshooting rate limiter designer-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Rate Limiter Designer Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement rate limiter designer for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended rate limiter designer approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When rate limiter designer must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
533 lines · 2,321 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Rate Limiter Designer bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for