Rate Limiting

API rate limiting policies and best practices

Rate Limiting

Learn about API rate limiting policies, headers, and how to handle rate limit responses.

Overview

All APIs implement rate limiting to ensure fair usage and maintain system stability. Understanding these limits helps you build more robust integrations.

Note: Rate limits are applied per API key and are reset at regular intervals. Always check the rate limit headers in API responses.

Rate Limit Policies

Standard Limits

Portfolio APIs

Public endpoints with basic rate limiting

Limit: 100 requests per minute
Window: 60 seconds
Reset: Rolling window

Authenticated APIs

Higher limits for authenticated requests

Limit: 1000 requests per hour
Window: 3600 seconds
Reset: Fixed window

Premium Limits

For enterprise customers and partners:

Limit: 10,000 requests per hour
Burst: 500 requests per minute
Support: Dedicated support channel

Rate Limit Headers

All API responses include rate limiting information in the headers:

📄Http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
X-RateLimit-Used: 5

Header Descriptions

X-RateLimit-Limit: Maximum requests allowed in the current window
X-RateLimit-Remaining: Number of requests remaining in current window
X-RateLimit-Reset: Unix timestamp when the rate limit resets
X-RateLimit-Used: Number of requests used in current window

Handling Rate Limits

429 Too Many Requests

When rate limits are exceeded, APIs return a 429 status code:

📋JSON

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "details": {
      "limit": 100,
      "used": 100,
      "reset_time": "2021-12-31T23:59:59Z"
    }
  }
}

Retry Strategies

Exponential Backoff

🟨JavaScript

async function callAPIWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = Math.min(
          2 ** attempt * 1000, // Exponential backoff
          parseInt(resetTime) * 1000 - Date.now() // Wait until reset
        );
        
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Respect Rate Limit Headers

🟨JavaScript

function checkRateLimit(response) {
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const reset = parseInt(response.headers.get('X-RateLimit-Reset'));
  
  if (remaining < 10) {
    const waitTime = (reset * 1000) - Date.now();
    console.warn(`Rate limit low. Consider waiting ${waitTime}ms`);
  }
  
  return {
    remaining,
    reset: new Date(reset * 1000),
    shouldWait: remaining < 5
  };
}

Best Practices

1. Monitor Usage

Track your API usage to avoid hitting limits:

🟨JavaScript

class APIClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.metrics = {
      requests: 0,
      rateLimitHits: 0,
      lastReset: null
    };
  }
  
  async request(endpoint, options = {}) {
    const response = await fetch(endpoint, {
      ...options,
      headers: {
        'X-API-Key': this.apiKey,
        ...options.headers
      }
    });
    
    this.updateMetrics(response);
    return response;
  }
  
  updateMetrics(response) {
    this.metrics.requests++;
    
    if (response.status === 429) {
      this.metrics.rateLimitHits++;
    }
    
    const reset = response.headers.get('X-RateLimit-Reset');
    if (reset) {
      this.metrics.lastReset = new Date(parseInt(reset) * 1000);
    }
  }
}

2. Implement Caching

Reduce API calls by caching responses:

🟨JavaScript

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function cachedAPICall(url) {
  const cached = cache.get(url);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const response = await fetch(url);
  const data = await response.json();
  
  cache.set(url, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

3. Batch Requests

When possible, batch multiple operations:

🟨JavaScript

// Instead of multiple single requests
const user1 = await api.getUser(1);
const user2 = await api.getUser(2);
const user3 = await api.getUser(3);

// Use batch endpoint
const users = await api.getUsers([1, 2, 3]);