API Rate Limits

Direct Answer

API requests are rate limited based on your plan to ensure fair usage and system stability. Limits are enforced per API key with different tiers for Free, Starter, Pro, and Enterprise plans.

Rate Limit Tiers

PlanRequests/MinuteRequests/DayBurst
Free601,00010
Starter30010,00050
Pro1,00050,000200
EnterpriseCustomCustomCustom
Burst: Additional requests allowed in short bursts

Rate Limit Headers

Every API response includes rate limit headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1609459200
X-RateLimit-Used: 13

Header Descriptions:

  • X-RateLimit-Limit: Total requests allowed in window
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets
  • X-RateLimit-Used: Requests used in current window

When Rate Limited

Response

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459200


{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry in 45 seconds.",
    "retry_after": 45
  }
}

Handling 429 Responses

async function makeRequest(url) {
  const response = await fetch(url, {
    headers: {
      'Authorization': Bearer ${API_KEY}
    }
  });
  
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    console.log(Rate limited. Retry after ${retryAfter}s);
    
    // Wait and retry
    await sleep(retryAfter  1000);
    return makeRequest(url);
  }
  
  return response.json();
}

Best Practices

1. Implement Exponential Backoff

async function requestWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      
      if (response.status === 429) {
        const delay = Math.pow(2, i)  1000; // 1s, 2s, 4s
        await sleep(delay);
        continue;
      }
      
      return response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

2. Monitor Rate Limit Headers

function checkRateLimit(response) {
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const limit = response.headers.get('X-RateLimit-Limit');
  
  const percentageUsed = ((limit - remaining) / limit)  100;
  
  if (percentageUsed > 80) {
    console.warn('Approaching rate limit:', percentageUsed + '%');
  }
}

3. Cache Responses

const cache = new Map();


async function cachedRequest(url, ttl = 300000) {
  const cached = cache.get(url);
  
  if (cached && Date.now() - cached.timestamp < ttl) {
    return cached.data;
  }
  
  const data = await makeRequest(url);
  cache.set(url, { data, timestamp: Date.now() });
  
  return data;
}

4. Batch Requests

Instead of: 

// DON'T: Multiple individual requests
for (const id of ids) {
  await fetch(/api/v1/items/${id});
}

Do: 

// DO: Single batch request
await fetch('/api/v1/items/batch', {
  method: 'POST',
  body: JSON.stringify({ ids })
});

5. Use Webhooks

For real-time updates, use webhooks instead of polling:

// DON'T: Poll every minute
setInterval(() => {
  fetch('/api/v1/status');
}, 60000);


// DO: Use webhooks
// Set up webhook at /your/webhook/endpoint
// We'll notify you when status changes

Rate Limit Windows

Rolling Window

Rate limits use a rolling window:

  • Not calendar-based
  • Resets continuously
  • More flexible than fixed windows

Example:

  • Limit: 100 requests/minute
  • Request 1 at 10:00:00
  • Request 100 at 10:00:30
  • Can make request 101 at 10:01:00 (60s after request 1)

Increasing Limits

Upgrade Plan

Higher plans have higher limits:

  1. Go to Billing → Plans
  2. Upgrade to Starter, Pro, or Enterprise
  3. Limits increase immediately

Enterprise Custom Limits

Need higher limits?

  1. Contact sales: [SALES_EMAIL]
  2. Discuss requirements
  3. Custom limits configured

Endpoint-Specific Limits

Some endpoints have additional limits:

EndpointAdditional Limit
/v1/export10 requests/hour
/v1/batch/5 requests/minute
/v1/search100 requests/minute

Troubleshooting

Unexpected rate limiting

Check:

  • Multiple API keys using same account?
  • Shared IP address?
  • Burst requests exceeding burst limit?
  • Check dashboard usage

Rate limit not resetting

Solutions:

  • Verify using latest timestamp
  • Check server time synchronization
  • Contact support if persists

FAQs

Q: Are rate limits per API key or per account? A: Per API key. Multiple keys share the account limit.

Q: Do failed requests count toward limits? A: Yes, all requests count including 4xx and 5xx errors.

Q: Can I check my current usage? A: Yes, via rate limit headers or dashboard.

Q: What happens if I exceed limits? A: Requests return 429. No data loss, just wait and retry.

Related Documentation:

Need Higher Limits? Contact Sales