Rate Limits

The Uberduck API implements rate limiting to ensure fair usage and system stability. This page explains the rate limits and how to handle them in your applications.

Rate Limit Tiers

Rate limits vary based on your subscription tier:

Tier	Requests per Minute	Requests per Day	Character Limit per Request
Free	5	100	10,000
Pro	60	1,000	20,000
Enterprise	Custom	Custom	Custom

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

Header	Description
X-RateLimit-Limit	The maximum number of requests you're permitted to make per time window.
X-RateLimit-Remaining	The number of requests remaining in the current time window.
X-RateLimit-Reset	The time at which the current rate limit window resets, in Unix time.

Rate Limit Exceeded Response

When you exceed your rate limit, the API will respond with a 429 Too Many Requests status code and the following error response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again in 47 seconds.",
    "details": {
      "reset_at": 1621506789,
      "retry_after": 47
    }
  }
}

The details object includes:

• reset_at: Unix timestamp when the rate limit will reset
• retry_after: Number of seconds to wait before retrying

Handling Rate Limits

To handle rate limits effectively in your application:

1. Implement Exponential Backoff

When you receive a 429 response, wait the suggested time before retrying:

async function makeRequestWithRetry(url, options, maxRetries = 5) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status !== 429) {
        return response;
      }
      
      const errorData = await response.json();
      const retryAfter = errorData.error.details.retry_after || 1;
      
      console.log(`Rate limited. Waiting ${retryAfter} seconds before retrying...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      
      retries++;
    } catch (error) {
      console.error('Request failed:', error);
      throw error;
    }
  }
  
  throw new Error('Max retries exceeded');
}

2. Monitor Rate Limit Headers

Check the rate limit headers in your responses to understand your current usage:

function checkRateLimits(response) {
  const limit = response.headers.get('X-RateLimit-Limit');
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');
  
  console.log(`Rate limits: ${remaining}/${limit} requests remaining, resets at ${new Date(reset * 1000)}`);
  
  // If we're running low on remaining requests, we might want to slow down
  if (remaining < limit * 0.1) {
    console.warn('Running low on rate limit, consider slowing down requests');
  }
  
  return response;
}

3. Implement Request Queuing

For high-volume applications, implement a request queue to control the rate of requests:

class RequestQueue {
  constructor(maxRequestsPerMinute) {
    this.queue = [];
    this.processing = false;
    this.maxRequestsPerMinute = maxRequestsPerMinute;
    this.requestsThisMinute = 0;
    this.minuteStart = Date.now();
  }
  
  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      
      if (!this.processing) {
        this.process();
      }
    });
  }
  
  async process() {
    if (this.queue.length === 0) {
      this.processing = false;
      return;
    }
    
    this.processing = true;
    
    // Check if we need to reset our minute counter
    const now = Date.now();
    if (now - this.minuteStart > 60000) {
      this.requestsThisMinute = 0;
      this.minuteStart = now;
    }
    
    // If we've hit our rate limit, wait until the next minute
    if (this.requestsThisMinute >= this.maxRequestsPerMinute) {
      const timeToWait = 60000 - (now - this.minuteStart);
      await new Promise(resolve => setTimeout(resolve, timeToWait));
      this.requestsThisMinute = 0;
      this.minuteStart = Date.now();
    }
    
    const { requestFn, resolve, reject } = this.queue.shift();
    
    try {
      this.requestsThisMinute++;
      const result = await requestFn();
      resolve(result);
    } catch (error) {
      reject(error);
    }
    
    // Process next request
    this.process();
  }
}

Requesting Higher Rate Limits

If you need higher rate limits than what your current tier provides, you can:

1. Upgrade to a higher subscription tier
2. Contact support@uberduck.ai for custom rate limit solutions (Enterprise tier)

Enterprise customers can request custom rate limits tailored to their specific needs.