​
Rate Limiting

The Lightyshare API implements rate limiting to ensure fair usage and prevent abuse of our services.

​
How Rate Limiting Works

Rate limits are applied per API token and are designed to allow normal usage while preventing excessive requests that could impact service performance.

​
Rate Limit Headers

The API includes rate limit information in response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
  • X-RateLimit-Limit: Maximum requests allowed in the time window
  • X-RateLimit-Remaining: Number of requests remaining in the current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

​
Rate Limit Responses

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "Request limit exceeded"
}
The response also includes a Retry-After header indicating how long to wait before retrying: 
Retry-After: 60

​
Handling Rate Limits

​
Exponential Backoff

Implement exponential backoff when you receive a 429 response: 
const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
        
        console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
        await delay(waitTime);
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await delay(Math.pow(2, attempt) * 1000);
    }
  }
}

​
Monitoring Rate Limits

Monitor the rate limit headers to avoid hitting limits: 
const response = await fetch(url, options);
const remaining = response.headers.get('X-RateLimit-Remaining');
const limit = response.headers.get('X-RateLimit-Limit');

if (parseInt(remaining) < 10) {
  console.warn(`Rate limit warning: ${remaining}/${limit} requests remaining`);
}

​
Best Practices

​
1. Implement Proper Retry Logic

  • Use exponential backoff when retrying after rate limit errors
  • Respect the Retry-After header when provided
  • Limit the number of retry attempts to prevent infinite loops

​
2. Monitor Your Usage

  • Track rate limit headers to understand your usage patterns
  • Implement alerts when approaching rate limits
  • Optimize your requests to minimize unnecessary API calls

​
3. Optimize Request Patterns

  • Batch requests when possible to reduce the number of API calls
  • Cache responses to avoid redundant requests
  • Use pagination for large datasets instead of making many small requests

​
4. Handle Errors Gracefully

  • Don’t panic when you hit rate limits - it’s a normal part of API usage
  • Provide user feedback when operations are temporarily unavailable
  • Queue operations that can be retried later

​
Rate Limit Tiers

Different API tokens may have different rate limits based on your usage tier:
  • Standard: Basic rate limits for normal usage
  • Premium: Higher limits for high-volume integrations
  • Enterprise: Custom limits for enterprise customers
Contact support if you need higher rate limits for your use case.

​
Testing Rate Limits

When testing your integration, be mindful of rate limits:
  • Use test tokens with appropriate limits
  • Implement proper delays between test requests
  • Monitor your test usage to avoid affecting production limits