Rate Limiting

API requests are rate-limited per organization to ensure fair usage and system stability. Rate limit information is included in response headers.

Rate Limit Headers

Every API response includes these headers:

Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

Rate Limit Exceeded

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retryAfter": 60
  }
}

The retryAfter field indicates the number of seconds to wait before retrying.

Handling Rate Limits

When you receive a 429 response, implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const errorData = await response.json();
      const retryAfter = errorData.error?.retryAfter || Math.pow(2, i) * 60;
      
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for i in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 429:
            error_data = response.json()
            retry_after = error_data.get('error', {}).get('retryAfter', 2 ** i * 60)
            
            print(f"Rate limited. Retrying after {retry_after} seconds...")
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception('Max retries exceeded')

Monitoring Rate Limits

Always check the rate limit headers in responses to monitor your usage:

const response = await fetch(url, options);
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0');

if (remaining < 10) {
  console.warn(`Low rate limit remaining: ${remaining}. Resets at ${new Date(resetTime * 1000)}`);
}

Rate limits are applied per organization. Different API keys from the same organization share the same rate limit pool.

Best Practices

Monitor rate limit headers in all responses
Implement exponential backoff when receiving 429 responses
Cache responses when possible to reduce API calls
Use webhooks instead of polling for status updates
Batch operations when possible (e.g., bulk invite instead of individual invites)