Rate Limits

Time:     10:00   10:15   10:30   10:45   11:00
Requests:  [250] → [180] → [220] → [200] → [150]
Limit:     1000/hour

At 10:45:
  Requests in last hour = 180 + 220 + 200 = 600
  Remaining = 1000 - 600 = 400 ✓

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1699127600

const response = await fetch(url, options);

const rateLimit = {
  limit: parseInt(response.headers.get('X-RateLimit-Limit')),
  remaining: parseInt(response.headers.get('X-RateLimit-Remaining')),
  reset: parseInt(response.headers.get('X-RateLimit-Reset'))
};

console.log(`${rateLimit.remaining}/${rateLimit.limit} requests remaining`);

// Check if approaching limit
if (rateLimit.remaining < 10) {
  console.warn('Approaching rate limit!');
  // Slow down or pause requests
}

{
  "error": {
    "type": "rate_limit_exceeded",
    "title": "Rate Limit Exceeded",
    "status": 429,
    "detail": "You have exceeded the rate limit of 1,000 requests per hour.",
    "metadata": {
      "limit": 1000,
      "retry_after": 3600,
      "current_usage": 1000
    },
    "links": {
      "docs": "https://docs.getbluma.com/concepts/rate-limits",
      "upgrade": "https://getbluma.com/billing"
    }
  }
}

Retry-After: 3600

async function apiCallWithBackoff(url: string, options: RequestInit, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      const backoffTime = Math.min(retryAfter * 1000, Math.pow(2, attempt) * 1000);

      console.log(`Rate limited. Retrying in ${backoffTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, backoffTime));
      continue;
    }

    return response;
  }

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

class RateLimitedQueue {
  private queue: Array<() => Promise<any>> = [];
  private processing = false;
  private requestsThisHour = 0;
  private hourStart = Date.now();
  private limit = 1000;

  async enqueue<T>(fn: () => Promise<T>): Promise<T> {
    return new Promise((resolve, reject) => {
      this.queue.push(async () => {
        try {
          const result = await fn();
          resolve(result);
        } catch (error) {
          reject(error);
        }
      });
      this.processQueue();
    });
  }

  private async processQueue() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;

    while (this.queue.length > 0) {
      // Reset counter if hour has passed
      if (Date.now() - this.hourStart > 3600000) {
        this.requestsThisHour = 0;
        this.hourStart = Date.now();
      }

      // Check if under limit
      if (this.requestsThisHour >= this.limit) {
        const waitTime = 3600000 - (Date.now() - this.hourStart);
        console.log(`Rate limit reached. Waiting ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      // Process next request
      const task = this.queue.shift();
      if (task) {
        await task();
        this.requestsThisHour++;
      }

      // Small delay between requests
      await new Promise(resolve => setTimeout(resolve, 100));
    }

    this.processing = false;
  }
}

// Usage
const queue = new RateLimitedQueue();

for (let i = 0; i < 100; i++) {
  queue.enqueue(() => fetch(url, options));
}

async function monitorRateLimit(response: Response) {
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
  const limit = parseInt(response.headers.get('X-RateLimit-Limit') || '0');
  const reset = parseInt(response.headers.get('X-RateLimit-Reset') || '0');

  const percentUsed = ((limit - remaining) / limit) * 100;

  if (percentUsed > 90) {
    console.error('⚠️ CRITICAL: 90%+ of rate limit used!');
    // Alert, slow down, or pause
  } else if (percentUsed > 75) {
    console.warn('⚠️ WARNING: 75%+ of rate limit used');
  }

  // Log to monitoring service
  metrics.gauge('api.rate_limit.remaining', remaining);
  metrics.gauge('api.rate_limit.percent_used', percentUsed);
}

// Production key (high traffic)
const prodKey = 'bluma_live_prod_key';

// Background jobs key (batch operations)
const batchKey = 'bluma_live_batch_key';

// Development key (testing)
const devKey = 'bluma_test_dev_key';

Free → Starter:    100 → 1,000 req/hr (10x)
Starter → Pro:     1,000 → 5,000 req/hr (5x)
Pro → Enterprise:  5,000 → 50,000 req/hr (10x)

curl -X POST https://api.getbluma.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rate Limit Test Key",
    "environment": "test",
    "rate_limit_per_hour": 10
  }'