Rate Limiting

Understand and work with API rate limits

Overview

The SnapTrack API enforces rate limiting to ensure fair usage and system stability. Rate limits are based on your subscription plan and reset every minute.

Rate Limits by Plan

Plan	Rate Limit	Requests per Hour
Free	No API access	-
Starter	5 requests/minute	300 requests/hour
Pro	20 requests/minute	1,200 requests/hour
Business	60 requests/minute	3,600 requests/hour

Rate Limit Headers

Every API response includes rate limit information in the headers:

Header	Description
X-RateLimit-Limit	Maximum requests per minute for your plan
X-RateLimit-Remaining	Requests remaining in this minute
X-RateLimit-Reset	Unix timestamp when the limit resets

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 18
X-RateLimit-Reset: 1609459200

When You Hit the Limit

If you exceed your rate limit, you'll receive a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459260

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "You have exceeded the API rate limit of 5 requests per minute",
  "limit": 5,
  "current": 5,
  "reset_at": "2025-01-27T15:31:00Z"
}

Best Practices

1. Monitor Remaining Requests

// JavaScript
const remaining = response.headers.get('X-RateLimit-Remaining');

if (remaining < 5) {
  console.warn('Approaching rate limit');
}

2. Implement Backoff Strategy

async function apiCallWithBackoff(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${token}` }
    });

    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const delay = parseInt(resetTime) * 1000 - Date.now();
      
      console.log(`Rate limited. Waiting ${delay}ms...`);
      await new Promise(r => setTimeout(r, Math.max(delay, 0)));
      continue;
    }

    return response;
  }
}

3. Batch Requests

Combine operations when possible:

// ❌ Bad: 5 separate requests
for (let i = 0; i < 5; i++) {
  await api.getWebsite(ids[i]);
}

// ✅ Good: Get all at once
const websites = await api.getWebsites();

4. Cache Results

const cache = new Map();

async function getCachedWebsite(id) {
  if (cache.has(id)) {
    return cache.get(id);
  }

  const website = await api.getWebsite(id);
  cache.set(id, website);
  return website;
}

5. Schedule Bulk Operations

// Spread requests over time
async function bulkScreenshots(websiteIds) {
  for (const id of websiteIds) {
    await api.takeScreenshot(id);
    await new Promise(r => setTimeout(r, 12000)); // 12 seconds (5 req/min)
  }
}

Upgrade Your Plan

If you're consistently hitting your rate limit, consider upgrading:

Current Plan	Upgrade To	Increase
Starter (5/min)	Pro (20/min)	4x increase
Pro (20/min)	Business (60/min)	3x increase

View Pricing

Rate Limit Examples

Starter Plan (5 requests/minute)

✅ 5 requests to list websites
✅ 2 requests to create websites + 3 to list screenshots
❌ 6 requests (exceeds limit)

Pro Plan (20 requests/minute)

✅ 20 individual website reads
✅ 5 batch operations with multiple sub-calls
❌ 21 requests (exceeds limit)

Debugging Rate Limits

Check Current Status

curl -X GET http://localhost:8000/api/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -i  # Shows headers

View Rate Limit Info

const response = await fetch('/api/test', {
  headers: { 'Authorization': `Bearer ${token}` }
});

console.log('Limit:', response.headers.get('X-RateLimit-Limit'));
console.log('Remaining:', response.headers.get('X-RateLimit-Remaining'));
console.log('Reset:', new Date(response.headers.get('X-RateLimit-Reset') * 1000));

FAQ

Q: Do rate limits reset hourly or daily?

A: Rate limits reset every minute. For example, if you make 5 requests at 1:00:05, your counter resets at 1:01:00.

Q: What happens if I go over my limit?

A: You'll receive a 429 response. Wait until the reset time to make more requests.

Q: How can I increase my rate limit?

A: Upgrade to a higher plan. You can upgrade anytime from your billing settings.

Q: Are webhooks rate limited?

A: Webhooks have separate limits (coming soon).

Next: Error Handling →