Rate Limiting

To ensure fair usage and maintain the stability of our service, the Roozna API implements rate limiting. This guide will help you understand how our rate limiting works and how to best manage your API requests.

How rate limiting works

Roozna uses a sliding window rate limit based on your API key. Each API key has a limit on the number of requests it can make within a specific time window.

Rate limit headers

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

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

Rate Limit Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1623869320

Rate limit tiers

Different API plans have different rate limits. Here's an overview of our current rate limit tiers:

Name
Basic
Description
1,000 requests per hour
Name
Pro
Description
5,000 requests per hour
Name
Enterprise
Description
Custom limits based on your needs

Handling rate limit errors

If you exceed your rate limit, the API will return a 429 Too Many Requests status code. The response will include a Retry-After header indicating the number of seconds to wait before making another request.

Best practices for handling rate limits

Monitor your usage: Keep track of the rate limit headers in your responses to understand your current usage.
Implement exponential backoff: When you receive a rate limit error, wait for the time specified in the Retry-After header before retrying. If you continue to receive errors, implement an exponential backoff strategy.
Optimize your requests: Minimize the number of API calls you make by using pagination effectively and caching results where appropriate.
Use multiple API keys: If you have different components of your application with varying request volumes, consider using separate API keys for each to avoid a high-volume component from affecting others.

Rate Limit Error Handling

import axios from 'axios'

async function makeApiRequest() {
  try {
    const response = await axios.get('https://api.roozna.com/v1/search', {
      headers: { 'X-API-Key': 'your_api_key' },
      params: { q: 'tech startups' }
    })
    return response.data
  } catch (error) {
    if (error.response && error.response.status === 429) {
      const retryAfter = error.response.headers['retry-after']
      console.log(`Rate limited. Retrying after ${retryAfter} seconds`)
      // Wait for the specified time before retrying
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
      // Retry the request
      return makeApiRequest()
    }
    // Handle other errors
    throw error
  }
}

Increasing your rate limit

If you find that you're consistently hitting your rate limits, you have a few options:

Optimize your usage: Review your API usage patterns and see if there are opportunities to reduce the number of requests you're making.
Upgrade your plan: Consider upgrading to a higher tier plan with a higher rate limit.
Contact us: If you have specific needs that aren't met by our standard plans, please contact our sales team to discuss custom rate limit options.

Conclusion

Understanding and properly managing rate limits is crucial for building reliable applications with the Roozna API. By following the best practices outlined in this guide, you can ensure that your application makes efficient use of the API and provides a smooth experience for your users.

Learn more about rate limit errors