Rate Limits

Overview

Oquira imposes rate limits on API requests to ensure system stability, fair usage, and protection against abuse. Understanding these limits will help you design robust integrations.

Rate Limit Types

API Key Rate Limits

Each API key has dedicated rate limits based on your subscription plan:

Plan	Requests/minute	Requests/day
Free	60	1,000
Starter	300	10,000
Business	1,000	100,000
Enterprise	Custom	Custom

IP-Based Rate Limits

A secondary rate limit applies per IP address to prevent abuse:

General: 100 requests per minute per IP
Authentication endpoints: 10 requests per minute per IP

Response Headers

Every API response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the current window resets
`Retry-After`	Seconds to wait before retrying (only on `429` responses)

Example Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1710936000

API Key Specific Headers

When using API keys, additional headers provide key-specific usage information:

Header	Description
`X-API-RateLimit-Limit`	Total requests allowed for this API key per window
`X-API-RateLimit-Remaining`	Requests remaining for this API key
`X-API-RateLimit-Reset`	When the API key's rate limit resets (UTC epoch)

Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a 429 Too Many Requests status:

{
  "success": false,
  "error": {
    "code": "API_RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "details": {
      "retryAfter": 30,
      "limit": 1000,
      "reset": "2024-03-20T10:01:00Z"
    },
    "timestamp": "2024-03-20T10:00:30.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Best Practices

1. Monitor Your Usage

Check the X-RateLimit-Remaining header in responses to track your approaching limits.

const response = await fetch("https://api.oquira.com/v1/business/queues", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const remaining = response.headers.get("X-RateLimit-Remaining");
if (remaining < 100) {
  console.warn(`Low rate limit: ${remaining} requests remaining`);
}

2. Implement Exponential Backoff

When you receive a 429 response, wait before retrying:

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After") || 30;
      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
      await new Promise((resolve) => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }
  throw new Error("Max retries exceeded");
}

3. Cache Results

Avoid redundant API calls by caching data that doesn't change frequently:

const cache = new Map();
const CACHE_TTL = 60000; // 1 minute

async function getCachedData(key, fetchFn) {
  const cached = cache.get(key);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await fetchFn();
  cache.set(key, { data, timestamp: Date.now() });
  return data;
}

4. Use Webhooks for Real-Time Updates

Instead of polling endpoints for changes, subscribe to webhooks:

Polling: Makes repeated API calls, consuming rate limit
Webhooks: Receive push notifications only when data changes

See Webhooks for setup instructions.

5. Batch Requests Where Possible

Some endpoints support batch operations that reduce the number of API calls:

# Instead of multiple calls:
# curl -X GET "https://api.oquira.com/v1/business/services/srv_1" ...
# curl -X GET "https://api.oquira.com/v1/business/services/srv_2" ...
# curl -X GET "https://api.oquira.com/v1/business/services/srv_3" ...

# Use a single list call with filters:
curl -X GET "https://api.oquira.com/v1/business/services?ids=srv_1,srv_2,srv_3" \
  -H "X-API-Key: your_api_key_here"

6. Implement Request Queuing

For high-volume applications, queue and throttle outgoing requests:

class RequestQueue {
  constructor(maxPerSecond = 10) {
    this.queue = [];
    this.interval = 1000 / maxPerSecond;
    this.processing = false;
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;
    this.processing = true;

    const { requestFn, resolve, reject } = this.queue.shift();
    try {
      const result = await requestFn();
      resolve(result);
    } catch (error) {
      reject(error);
    }

    setTimeout(() => {
      this.processing = false;
      this.process();
    }, this.interval);
  }
}

Plan Limits

Beyond rate limits, each plan has monthly quotas:

Plan	Monthly Tickets	Monthly API Calls	Webhooks
Free	500	10,000	1
Starter	5,000	100,000	5
Business	50,000	1,000,000	25
Enterprise	Unlimited	Unlimited	Unlimited

Quota Exceeded

If you exceed your monthly quota, the API returns a 403 Forbidden:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly API call quota exceeded",
    "details": {
      "limit": 10000,
      "used": 10000,
      "resetsAt": "2024-04-01T00:00:00Z"
    }
  }
}

Upgrading Your Plan

To increase your limits:

Go to Settings > Billing in your dashboard
Select a plan that meets your needs
Limits are updated immediately upon upgrade

For enterprise needs, contact support@oquira.com.

Next Steps

Webhooks - Reduce API calls with real-time notifications
Errors - Handle rate limit errors gracefully
Responses - Understand response formats

Overview

Oquira imposes rate limits on API requests to ensure system stability, fair usage, and protection against abuse. Understanding these limits will help you design robust integrations.

Rate Limit Types

API Key Rate Limits

Each API key has dedicated rate limits based on your subscription plan:

Plan	Requests/minute	Requests/day
Free	60	1,000
Starter	300	10,000
Business	1,000	100,000
Enterprise	Custom	Custom

IP-Based Rate Limits

A secondary rate limit applies per IP address to prevent abuse:

General: 100 requests per minute per IP
Authentication endpoints: 10 requests per minute per IP

Response Headers

Every API response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the current window resets
`Retry-After`	Seconds to wait before retrying (only on `429` responses)

Example Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1710936000

API Key Specific Headers

When using API keys, additional headers provide key-specific usage information:

Header	Description
`X-API-RateLimit-Limit`	Total requests allowed for this API key per window
`X-API-RateLimit-Remaining`	Requests remaining for this API key
`X-API-RateLimit-Reset`	When the API key's rate limit resets (UTC epoch)

Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a 429 Too Many Requests status:

{
  "success": false,
  "error": {
    "code": "API_RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "details": {
      "retryAfter": 30,
      "limit": 1000,
      "reset": "2024-03-20T10:01:00Z"
    },
    "timestamp": "2024-03-20T10:00:30.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Best Practices

1. Monitor Your Usage

Check the X-RateLimit-Remaining header in responses to track your approaching limits.

const response = await fetch("https://api.oquira.com/v1/business/queues", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const remaining = response.headers.get("X-RateLimit-Remaining");
if (remaining < 100) {
  console.warn(`Low rate limit: ${remaining} requests remaining`);
}

2. Implement Exponential Backoff

When you receive a 429 response, wait before retrying:

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After") || 30;
      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
      await new Promise((resolve) => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }
  throw new Error("Max retries exceeded");
}

3. Cache Results

Avoid redundant API calls by caching data that doesn't change frequently:

const cache = new Map();
const CACHE_TTL = 60000; // 1 minute

async function getCachedData(key, fetchFn) {
  const cached = cache.get(key);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await fetchFn();
  cache.set(key, { data, timestamp: Date.now() });
  return data;
}

4. Use Webhooks for Real-Time Updates

Instead of polling endpoints for changes, subscribe to webhooks:

Polling: Makes repeated API calls, consuming rate limit
Webhooks: Receive push notifications only when data changes

See Webhooks for setup instructions.

5. Batch Requests Where Possible

Some endpoints support batch operations that reduce the number of API calls:

# Instead of multiple calls:
# curl -X GET "https://api.oquira.com/v1/business/services/srv_1" ...
# curl -X GET "https://api.oquira.com/v1/business/services/srv_2" ...
# curl -X GET "https://api.oquira.com/v1/business/services/srv_3" ...

# Use a single list call with filters:
curl -X GET "https://api.oquira.com/v1/business/services?ids=srv_1,srv_2,srv_3" \
  -H "X-API-Key: your_api_key_here"

6. Implement Request Queuing

For high-volume applications, queue and throttle outgoing requests:

class RequestQueue {
  constructor(maxPerSecond = 10) {
    this.queue = [];
    this.interval = 1000 / maxPerSecond;
    this.processing = false;
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;
    this.processing = true;

    const { requestFn, resolve, reject } = this.queue.shift();
    try {
      const result = await requestFn();
      resolve(result);
    } catch (error) {
      reject(error);
    }

    setTimeout(() => {
      this.processing = false;
      this.process();
    }, this.interval);
  }
}

Plan Limits

Beyond rate limits, each plan has monthly quotas:

Plan	Monthly Tickets	Monthly API Calls	Webhooks
Free	500	10,000	1
Starter	5,000	100,000	5
Business	50,000	1,000,000	25
Enterprise	Unlimited	Unlimited	Unlimited

Quota Exceeded

If you exceed your monthly quota, the API returns a 403 Forbidden:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly API call quota exceeded",
    "details": {
      "limit": 10000,
      "used": 10000,
      "resetsAt": "2024-04-01T00:00:00Z"
    }
  }
}

Upgrading Your Plan

To increase your limits:

Go to Settings > Billing in your dashboard
Select a plan that meets your needs
Limits are updated immediately upon upgrade

For enterprise needs, contact support@oquira.com.

Next Steps

Webhooks - Reduce API calls with real-time notifications
Errors - Handle rate limit errors gracefully
Responses - Understand response formats

Rate Limits

On this page

Rate Limits

On this page