Rate Limiting | Bootspring Docs

Bootspring API implements rate limiting to ensure fair usage and system stability.

Rate Limits by Plan#

Plan	Requests/Minute	Requests/Hour	Requests/Day
Free	20	100	1,000
Pro	60	1,000	10,000
Team	120	5,000	50,000
Enterprise	Custom	Custom	Custom

Rate Limit Headers#

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705312800
X-RateLimit-Policy: 1000;w=3600

Header Descriptions#

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets
`X-RateLimit-Policy`	Rate limit policy (requests;w=window_seconds)

Rate Limit Exceeded#

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}

Endpoint-Specific Limits#

Some endpoints have additional rate limits:

Endpoint	Limit	Window
`POST /auth/device/code`	5	1 minute
`POST /auth/device/token`	20	1 minute
`POST /v1/track`	1000	1 minute
`GET /v1/agents`	100	1 minute

Handling Rate Limits#

JavaScript/TypeScript#

async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries: number = 3
): Promise<Response> {
  let retries = 0;

  while (retries < maxRetries) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get('Retry-After') || '60',
        10
      );

      console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
      await sleep(retryAfter * 1000);
      retries++;
      continue;
    }

    return response;
  }

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

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

Exponential Backoff#

async function fetchWithExponentialBackoff(
  url: string,
  options: RequestInit,
  maxRetries: number = 5
): Promise<Response> {
  let retries = 0;
  let delay = 1000; // Start with 1 second

  while (retries < maxRetries) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');

      // Use Retry-After if provided, otherwise use exponential backoff
      const waitTime = retryAfter
        ? parseInt(retryAfter, 10) * 1000
        : delay;

      console.log(`Rate limited. Waiting ${waitTime / 1000}s...`);
      await sleep(waitTime);

      delay *= 2; // Double the delay for next retry
      retries++;
      continue;
    }

    return response;
  }

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

Python#

import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session_with_retries():
    session = requests.Session()

    retry_strategy = Retry(
        total=3,
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["HEAD", "GET", "OPTIONS", "POST"],
        backoff_factor=1,
        respect_retry_after_header=True
    )

    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)

    return session

# Usage
session = create_session_with_retries()
response = session.get(
    "https://api.bootspring.dev/v1/projects",
    headers={"Authorization": "Bearer bs_xxx"}
)

Monitoring Rate Limits#

Track Remaining Requests#

class RateLimitTracker {
  private remaining: number = Infinity;
  private resetTime: number = 0;

  updateFromResponse(response: Response): void {
    const remaining = response.headers.get('X-RateLimit-Remaining');
    const reset = response.headers.get('X-RateLimit-Reset');

    if (remaining) {
      this.remaining = parseInt(remaining, 10);
    }
    if (reset) {
      this.resetTime = parseInt(reset, 10) * 1000;
    }
  }

  shouldWait(): boolean {
    return this.remaining <= 0 && Date.now() < this.resetTime;
  }

  getWaitTime(): number {
    if (!this.shouldWait()) return 0;
    return this.resetTime - Date.now();
  }

  getRemainingRequests(): number {
    return this.remaining;
  }
}

Proactive Rate Limiting#

class RateLimiter {
  private tokens: number;
  private lastRefill: number;
  private readonly maxTokens: number;
  private readonly refillRate: number; // tokens per ms

  constructor(requestsPerMinute: number) {
    this.maxTokens = requestsPerMinute;
    this.tokens = requestsPerMinute;
    this.lastRefill = Date.now();
    this.refillRate = requestsPerMinute / 60000;
  }

  async acquire(): Promise<void> {
    this.refill();

    if (this.tokens < 1) {
      const waitTime = (1 - this.tokens) / this.refillRate;
      await sleep(waitTime);
      this.refill();
    }

    this.tokens -= 1;
  }

  private refill(): void {
    const now = Date.now();
    const elapsed = now - this.lastRefill;
    this.tokens = Math.min(
      this.maxTokens,
      this.tokens + elapsed * this.refillRate
    );
    this.lastRefill = now;
  }
}

// Usage
const limiter = new RateLimiter(60); // 60 requests per minute

async function makeRequest() {
  await limiter.acquire();
  return fetch('https://api.bootspring.dev/v1/projects', {
    headers: { Authorization: 'Bearer bs_xxx' },
  });
}

Best Practices#

1. Cache Responses#

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 500,
  ttl: 1000 * 60 * 5, // 5 minutes
});

async function getProjects(): Promise<Project[]> {
  const cached = cache.get('projects');
  if (cached) return cached;

  const response = await fetch('/api/projects');
  const data = await response.json();

  cache.set('projects', data);
  return data;
}

2. Batch Requests#

// Instead of multiple requests
for (const id of projectIds) {
  await fetch(`/api/projects/${id}`);
}

// Use batch endpoint
await fetch('/api/projects/batch', {
  method: 'POST',
  body: JSON.stringify({ ids: projectIds }),
});

3. Use Webhooks#

Instead of polling, configure webhooks for real-time updates:

// Instead of polling every minute
setInterval(() => checkForUpdates(), 60000);

// Configure webhook to receive updates
// See /docs/api/endpoints/webhooks

4. Implement Request Queuing#

class RequestQueue {
  private queue: Array<() => Promise<any>> = [];
  private processing = false;
  private requestsThisMinute = 0;
  private readonly maxPerMinute: number;

  constructor(maxPerMinute: number) {
    this.maxPerMinute = maxPerMinute;
    setInterval(() => {
      this.requestsThisMinute = 0;
    }, 60000);
  }

  async add<T>(request: () => Promise<T>): Promise<T> {
    return new Promise((resolve, reject) => {
      this.queue.push(async () => {
        try {
          resolve(await request());
        } catch (error) {
          reject(error);
        }
      });
      this.process();
    });
  }

  private async process(): Promise<void> {
    if (this.processing) return;
    this.processing = true;

    while (this.queue.length > 0) {
      if (this.requestsThisMinute >= this.maxPerMinute) {
        await sleep(1000);
        continue;
      }

      const request = this.queue.shift();
      if (request) {
        this.requestsThisMinute++;
        await request();
      }
    }

    this.processing = false;
  }
}

Increasing Rate Limits#

Upgrade Your Plan#

Higher tier plans include increased rate limits. Visit Pricing to upgrade.

Enterprise Custom Limits#

For enterprise customers, we offer custom rate limits based on your needs. Contact sales@bootspring.dev.

Burst Allowance#

All plans include a burst allowance of 2x the per-minute limit for short spikes.