Rate Limiting

The API enforces rate limits to ensure fair usage and platform stability. This guide explains how limits work and how to handle them gracefully.

How Limits Work

Each API key is allowed a fixed number of requests within a rolling time window. When you exceed your limit, the API responds with a 429 Too Many Requests status.

Rate Limit Headers

Every response includes headers that help you track your usage in real time:

• X-RateLimit-Limit — the maximum number of requests allowed in the window
• X-RateLimit-Remaining — the number of requests left in the current window
• X-RateLimit-Reset — the Unix timestamp when the window resets

Handling 429 Responses

When you receive a 429, inspect the X-RateLimit-Reset header (or the Retry-After header when present) and wait before retrying. Implementing exponential backoff is strongly recommended.

Best Practices

• Cache responses where possible to reduce request volume
• Batch operations using the batch endpoint when available
• Monitor the remaining header and throttle proactively
• Never retry immediately in a tight loop

const response = await fetch('https://api.example.com/v2/users', {
  headers: { 'Authorization': `Bearer ${process.env.API_KEY}` }
});

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

async function requestWithRetry(url, options, retries = 3) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const reset = Number(res.headers.get('X-RateLimit-Reset')) * 1000;
    const wait = Math.max(reset - Date.now(), 2 ** attempt * 1000);
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error('Rate limit exceeded after retries');
}