Rate Limiting

Overview

To ensure fair usage and maintain service quality, the Omni API enforces rate limits on API requests. Rate limits are based on your subscription tier and are applied per API key.

Rate Limit Tiers

The current rate limits for each subscription tier are:

Rate Limit Headers

All API responses include headers that provide information about your current rate limit status:

Rate Limit Exceeded

When you exceed your rate limit, the API will return a 429 Too Many Requests response with the following body:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Handling Rate Limits

Here are some strategies for handling rate limits in your application:

Implement Exponential Backoff

When you receive a rate limit error, wait before retrying the request. Use an exponential backoff strategy to increase the wait time between retries.

async function makeRequestWithBackoff(url, options, maxRetries = 5) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Get the reset time from the headers
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = resetTime ? (parseInt(resetTime) * 1000) - Date.now() : Math.pow(2, retries) * 1000;
        
        console.log(`Rate limit exceeded. Waiting ${waitTime/1000} seconds before retrying.`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        retries++;
        continue;
      }
      
      return response;
    } catch (error) {
      console.error('Request failed:', error);
      retries++;
      
      if (retries >= maxRetries) {
        throw new Error('Max retries exceeded');
      }
      
      // Wait before retrying
      const waitTime = Math.pow(2, retries) * 1000;
      console.log(`Waiting ${waitTime/1000} seconds before retrying.`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
  }
}

Queue Requests

Implement a request queue to control the rate at which you make API requests. This can help you stay within your rate limits.

Monitor Usage

Keep track of your API usage to identify patterns and optimize your requests. The Omni dashboard provides detailed usage statistics to help you monitor your API usage.

Upgrade Your Plan

If you consistently hit your rate limits, consider upgrading to a higher tier plan. Higher tier plans offer higher rate limits and additional features to support your growing needs.

Best Practices

• Batch requests when possible - Instead of making multiple individual requests, batch them together to reduce the number of API calls
• Cache responses - Cache API responses when appropriate to reduce the number of requests
• Implement retry logic - Use exponential backoff when retrying failed requests
• Monitor usage patterns - Regularly review your API usage to identify optimization opportunities

Next Steps

• Explore the Moderate Content endpoint
• See examples of text moderation