Client makes request
    ↓
Check request count for this client
    ↓
Within limit? → ✅ Forward request → Increment counter
    ↓
Exceeded limit? → ❌ Return 429 Too Many Requests

Tenant: Acme Corp (Pro Plan)
Limit: 5,000 requests/minute (all routes + clients combined)

ALL traffic through KnoxCall cannot exceed 5k req/min

Free:        100 requests/minute
Standard:  1,000 requests/minute
Pro:       5,000 requests/minute
Enterprise: 10,000 requests/minute (customizable)

Bucket capacity: 5,000 tokens (requests)
Refill rate: 5,000 tokens/minute

Example:
  - 0:00:00 → 5,000 tokens available
  - 0:00:05 → Receive 2,000 requests (3,000 remaining)
  - 0:00:10 → 416 tokens refilled (3,416 remaining)
  - 0:00:15 → Receive burst of 4,000 requests
              ❌ Only 3,416 available → 584 requests rejected (429)

Route: stripe-webhooks
Limit: 10,000 requests/hour

ALL clients using this route combined cannot exceed 10k req/hour

Client: mobile-app-ios
Limit: 1,000 requests/hour

This specific client cannot exceed 1k req/hour across all routes

GET requests: 5,000/hour
POST requests: 1,000/hour
DELETE requests: 100/hour

1. Tenant limit: 5,000/min → ✅ Pass (3,000 used)
   ↓
2. Route limit: 1,000/hour → ✅ Pass (500 used)
   ↓
3. Client limit: 500/hour → ✅ Pass (200 used)
   ↓
4. Method limit (POST): 100/hour → ✅ Pass (50 used)
   ↓
5. Request forwarded to backend API

1000

hour

100

500 requests/hour

GET:
  Rate Limit: 5000/hour

POST:
  Rate Limit: 1000/hour

DELETE:
  Rate Limit: 100/hour

429 Too Many Requests

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000
Retry-After: 3600

{
  "error": "Rate limit exceeded",
  "message": "Tenant rate limit exceeded. Limit: 1000 requests per minute.",
  "limit": 1000,
  "remaining": 0,
  "resetAt": "2025-01-20T15:00:00Z",
  "retryAfter": 3600,
  "layer": "tenant"
}

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640000000

Your Plan: Pro (5,000 requests/minute)

Current Usage:
  ┌────────────────────────────────┐
  │████████░░░░░░░░░░░░░░░░░░░░░░│ 32% (1,600/5,000)
  └────────────────────────────────┘

Recent Activity (last 60 seconds):
  0:00 - 0:10: 400 requests
  0:10 - 0:20: 350 requests
  0:20 - 0:30: 420 requests
  0:30 - 0:40: 230 requests
  0:40 - 0:50: 150 requests
  0:50 - 1:00: 50 requests

Token Bucket Status:
  Available tokens: 3,400 / 5,000
  Refill rate: 83.3 tokens/second
  Time to full: 19.2 seconds

Free → Standard: 10x increase (100 → 1,000 req/min)
Standard → Pro: 5x increase (1,000 → 5,000 req/min)
Pro → Enterprise: 2x increase + custom limits (5,000 → 10,000+)

Base Limit: 1,000 requests/hour
Burst Allowance: 200 requests

Minute 1: 200 requests ✅ (burst)
Minute 2: 200 requests ✅ (burst)
Minute 3: 200 requests ✅ (burst)
Minute 4: 200 requests ✅ (burst)
Minute 5: 200 requests ✅ (burst)
Minute 6: 200 requests ❌ (burst depleted)
Remaining hour: ~17 requests/minute average

Free Tier Client:
  Limit: 100 requests/hour

Pro Tier Client:
  Limit: 1,000 requests/hour

Enterprise Client:
  Limit: 10,000 requests/hour

US Region: 5,000 requests/hour
EU Region: 3,000 requests/hour
APAC Region: 2,000 requests/hour

Alert Type: Rate Limit Exceeded
Threshold: 10 violations/hour
Channels: Email, Slack

Initial: 100 requests/hour
After monitoring: 500 requests/hour
Production stable: 1,000 requests/hour

Public API: 100/hour
Partner API: 1,000/hour
Internal Services: 10,000/hour

Base: 1,000/hour
Burst: +20% (1,200 total)

## Rate Limits

- **Free Tier**: 100 requests/hour
- **Pro Tier**: 1,000 requests/hour
- **Enterprise**: Custom limits

Headers included in every response.

Limit: 10,000 requests/hour
Burst: 500 requests
Reason: Webhooks can spike during events

Limit: 100 requests/hour per API key
Burst: 20 requests
Reason: Prevent abuse of public endpoints

Limit: 50,000 requests/hour
Burst: 5,000 requests
Reason: High-traffic internal communication

POST /payments: 10 requests/minute
GET /payments: 100 requests/minute
Reason: Prevent duplicate payment charges

async function makeRequestWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, i) * 1000;

      console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

const response = await fetch(url);

const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

if (remaining < 10) {
  console.warn(`Low on rate limit: ${remaining}/${limit} remaining`);
}

class RateLimitedQueue {
  constructor(maxRequestsPerHour) {
    this.maxRequests = maxRequestsPerHour;
    this.queue = [];
    this.requestTimestamps = [];
  }

  async enqueue(requestFn) {
    // Remove timestamps older than 1 hour
    const oneHourAgo = Date.now() - 3600000;
    this.requestTimestamps = this.requestTimestamps.filter(t => t > oneHourAgo);

    // Wait if at limit
    while (this.requestTimestamps.length >= this.maxRequests) {
      const oldestRequest = this.requestTimestamps[0];
      const waitTime = oldestRequest + 3600000 - Date.now();
      await new Promise(resolve => setTimeout(resolve, waitTime));
      this.requestTimestamps.shift();
    }

    this.requestTimestamps.push(Date.now());
    return await requestFn();
  }
}