Rate Limiting

Understand rate limits and how to handle them

Overview

To ensure fair usage and system stability, Orwel implements rate limiting on all API requests. Rate limits are applied per API key.

Rate Limits

Production Keys

1,000 requests per minute

Suitable for production workloads and high-traffic applications

Development Keys

100 requests per minute

Perfect for testing and development environments

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642252800

X-RateLimit-Limit · integer

Maximum number of requests allowed in the current window

X-RateLimit-Remaining · integer

Number of requests remaining in the current window

X-RateLimit-Reset · integer

Unix timestamp when the rate limit resets

Rate Limit Exceeded

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 60
}

The response also includes a Retry-After header indicating how many seconds to wait before retrying.

Best Practices

Monitor Rate Limit Headers

Always check the X-RateLimit-Remaining header to know how many requests you have left. Implement logic to slow down requests as you approach the limit.

const response = await fetch('https://api.orwel.io/api/v1/leads');
const remaining = response.headers.get('X-RateLimit-Remaining');

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

Implement Exponential Backoff

When you receive a 429 response, wait before retrying. Use exponential backoff to gradually increase wait times.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) {
      return response;
    }
    
    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, i) * 1000;
    
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  
  throw new Error('Max retries exceeded');
}

Batch Requests

Instead of making many individual requests, batch your operations when possible. For example, use pagination to fetch multiple items in a single request.

// ❌ Bad: Multiple requests
for (let i = 0; i < 100; i++) {
  await fetch(`/api/v1/leads/${ids[i]}`);
}

// ✅ Good: Single paginated request
const response = await fetch('/api/v1/leads?limit=100');

Cache Responses

Cache API responses when appropriate to reduce the number of requests. Use ETags or implement your own caching strategy.

const cache = new Map();

async function fetchWithCache(url) {
  if (cache.has(url)) {
    return cache.get(url);
  }
  
  const response = await fetch(url);
  const data = await response.json();
  cache.set(url, data);
  
  return data;
}

Monitoring Usage

Track your API usage in the Orwel dashboard:

1. Navigate to Settings → API Keys
2. View usage metrics for each key
3. Monitor rate limit violations
4. Set up alerts for high usage

Increasing Limits

If you need higher rate limits for your production workload:

1. Contact Support

   Email [e-mail] with your use case

2. Provide Details

   Include your workspace ID and expected request volume

3. Review

   Our team will review your request within 24 hours

Enterprise plans include higher rate limits by default. Contact sales to learn more.

Example Implementation

Here’s a complete example with rate limit handling:

class OrwelClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.orwel.io/api/v1';
  }
  
  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    };
    
    const response = await fetch(url, { ...options, headers });
    
    // Check rate limit
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After'));
      throw new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds`);
    }
    
    return response.json();
  }
  
  async getLeads(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    return this.request(`/leads?${queryString}`);
  }
}

// Usage
const client = new OrwelClient('your_api_key');

try {
  const leads = await client.getLeads({ limit: 50 });
  console.log(leads);
} catch (error) {
  console.error(error.message);
}