Documentation | KhaleejiAPI

Rate Limits

Understand how rate limiting works and how to handle it in your application.

Overview

Rate limits help ensure fair usage and protect the stability of our APIs. Limits are applied per API key and vary based on your subscription plan.

Plan	Requests/Minute	Requests/Month	Overage
Free	10	1,000	-
Starter	60	10,000	0.008/req
Professional	300	100,000	0.004/req
Business	1000	500,000	0.002/req
Enterprise	Custom	Custom	Custom/req

Response Headers

Every API response includes headers that help you track your rate limit status:

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

X-RateLimit-Limit

Maximum requests allowed per minute for your plan

X-RateLimit-Remaining

Requests remaining in the current window

X-RateLimit-Reset

Unix timestamp when the rate limit resets

Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests response. Here's how to handle it:

javascript

import { KhaleejiAPI } from '@khaleejiapi/sdk';
 
const client = new KhaleejiAPI('your_api_key', {
  // SDK handles rate limiting automatically
  retryOnRateLimit: true,
  maxRetries: 3
});
 
// Or handle manually
try {
  const result = await client.ip.lookup('8.8.8.8');
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    const retryAfter = error.retryAfter; // seconds to wait
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  }
}

Pro tip: Our official SDKs handle rate limiting automatically with exponential backoff. We recommend using them for the best experience.

Best Practices

Implement Caching

Cache API responses when possible to reduce the number of requests. Many of our endpoints return data that doesn't change frequently (e.g., IP geolocation).

Use Batch Requests

Some endpoints support batch operations. Use them to process multiple items in a single request instead of making multiple individual calls.

Monitor Your Usage

Keep track of your API usage in your dashboard. Set up alerts to notify you when you're approaching your limits.

Upgrade When Needed

If you consistently hit rate limits, consider upgrading your plan for higher limits and better overage rates.