Rate Limiting

Overview

The InstaView API implements production-ready rate limiting to ensure fair usage and system stability. Rate limits are enforced per API key with two-tier protection:

Per-minute limits: Burst protection (default: 60 requests/minute)
Per-hour limits: Quota enforcement (default: 2,000 requests/hour)

Rate limits can be customized per API key or per company based on your subscription plan.

How It Works

Our rate limiting system provides:

Fair enforcement: Smooth limit enforcement that prevents burst abuse
High performance: Minimal overhead (~2-5ms per request)
High availability: System stays available even during technical issues
Full visibility: Rate limit information in every response header

Response Headers

All API responses include rate limit information in HTTP headers:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Limit-Hour: 2000
X-RateLimit-Remaining-Minute: 45
X-RateLimit-Remaining-Hour: 1850
X-RateLimit-Reset-Minute: 1705320120
X-RateLimit-Reset-Hour: 1705323720

Header Descriptions:

X-RateLimit-Limit-Minute: Maximum requests allowed per minute
X-RateLimit-Limit-Hour: Maximum requests allowed per hour
X-RateLimit-Remaining-Minute: Requests remaining this minute
X-RateLimit-Remaining-Hour: Requests remaining this hour
X-RateLimit-Reset-Minute: Unix timestamp when minute limit resets
X-RateLimit-Reset-Hour: Unix timestamp when hour limit resets

Rate Limit Response

When you exceed the rate limit, you’ll receive:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "error": "Too Many Requests",
  "retryAfter": 30,
  "limit": 60,
  "remaining": 0,
  "reset": 1705320120
}

Response Fields:

retryAfter: Seconds to wait before retrying
limit: The limit that was exceeded
remaining: Always 0 when rate limited
reset: Unix timestamp when the limit resets

Subscription Plan Limits

Rate limits are automatically set based on your subscription plan:

Plan	Requests/Minute	Requests/Hour	Burst Size
Trial	30	500	50
Starter	120	5,000	200
Business	300	15,000	500
Scale	600	30,000	1,000
Enterprise	Custom	Custom	Custom

Rate limits follow your active subscription. Ask your account manager to upgrade your plan or to arrange custom limits.

Endpoints With Lower Limits

A few endpoints do more than read or write a record, and carry their own tighter budget on top of your plan’s limits. Staying inside your plan’s allowance is not enough for these — the narrower limit applies first.

Endpoint	Requests/Minute	Requests/Hour
`POST /agents/{id}/knowledge`	6	60
`POST /agents/{id}/knowledge/{documentId}/complete`	20	200

Starting a knowledge upload reserves a document slot and, once completed, a stored file — so it is limited well below ordinary traffic. Completing an upload is limited more generously, because retrying a failed completion should be cheap.

These responses carry a Retry-After header with the number of seconds to wait. They do not consume a different budget from your plan limits — they are an additional ceiling, not a separate allowance.

Best Practices

Use Request Queues

Implement request queuing in your application to avoid overwhelming the API:

class RequestQueue {
  constructor(concurrency = 5) {
    this.concurrency = concurrency;
    this.running = 0;
    this.queue = [];
  }
  
  async add(fn) {
    while (this.running >= this.concurrency) {
      await new Promise(resolve => this.queue.push(resolve));
    }
    
    this.running++;
    
    try {
      return await fn();
    } finally {
      this.running--;
      const next = this.queue.shift();
      if (next) next();
    }
  }
}

// Usage
const queue = new RequestQueue(5);
await queue.add(() => fetch('/api/endpoint'));

Cache Responses

Cache frequently accessed data to reduce API calls:

class APIClient {
  constructor(apiKey, cacheTTL = 60000) {
    this.apiKey = apiKey;
    this.cache = new Map();
    this.cacheTTL = cacheTTL;
  }
  
  async get(url) {
    const cached = this.cache.get(url);
    
    if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
      return cached.data;
    }
    
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${this.apiKey}` }
    });
    
    const data = await response.json();
    this.cache.set(url, { data, timestamp: Date.now() });
    
    return data;
  }
}

Batch Operations

When possible, batch multiple operations together:

// ❌ Multiple individual requests
for (const contact of contacts) {
  await api.post('/contacts', contact);
}

// ✅ Better: batch, and pace the batches against your actual per-minute limit.
// Pick a fixed batchSize/delay pair and you are guessing: 10 requests every 100ms is
// 6,000 a minute, which is ten times the Scale limit and two hundred times Trial's.
// Default to the lowest plan and let the response headers raise it.
async function processBatch(
  items,
  { batchSize = 5, requestsPerMinute = 30 } = {}
) {
  let limitPerMinute = requestsPerMinute;
  
  for (let i = 0; i < items.length; i += batchSize) {
    const startedAt = Date.now();
    const batch = items.slice(i, i + batchSize);
    const responses = await Promise.all(
      batch.map(item => api.post('/contacts', item))
    );
    
    // The API states its own ceiling on every response — trust it over the default.
    const advertised = Number(
      responses[0]?.headers?.get('X-RateLimit-Limit-Minute')
    );
    if (Number.isFinite(advertised) && advertised > 0) {
      limitPerMinute = advertised;
    }
    
    // A 429 on any request in the batch overrides the pacing entirely.
    const retryAfterMs = Math.max(
      0,
      ...responses.map(r => Number(r?.headers?.get('Retry-After')) * 1000 || 0)
    );
    
    if (i + batchSize >= items.length) break;
    
    const minIntervalMs = (60_000 / limitPerMinute) * batchSize;
    const waitMs = Math.max(
      retryAfterMs,
      minIntervalMs - (Date.now() - startedAt)
    );
    if (waitMs > 0) {
      await new Promise(resolve => setTimeout(resolve, waitMs));
    }
  }
}

Add Delays Between Requests

Add small delays between requests to avoid bursts:

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function processWithDelay(items, delayMs = 200) {
  const results = [];
  
  for (const item of items) {
    results.push(await processItem(item));
    await sleep(delayMs);
  }
  
  return results;
}

Implement Exponential Backoff

Be prepared for potential errors with exponential backoff:

async function exponentialBackoff(fn, maxRetries = 5) {
  let delay = 1000;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      
      await new Promise(resolve => setTimeout(resolve, delay));
      delay *= 2;
    }
  }
}

Monitoring Your Usage

Use the response headers to monitor your API usage:

const response = await fetch("/api/endpoint", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

const minuteLimit = response.headers.get("X-RateLimit-Limit-Minute");
const minuteRemaining = response.headers.get("X-RateLimit-Remaining-Minute");
const minuteReset = response.headers.get("X-RateLimit-Reset-Minute");

console.log(`Rate limit: ${minuteRemaining}/${minuteLimit} remaining`);
console.log(`Resets at: ${new Date(minuteReset * 1000).toISOString()}`);

Handling Rate Limits

Implement exponential backoff when you receive a 429 response:

async function makeRequestWithRetry(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") || Math.pow(2, attempt); // Exponential backoff

      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await sleep(retryAfter * 1000);
      continue;
    }

    return response;
  }

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

Custom Rate Limits

If you need custom rate limits for your use case:

Ask Your Account Manager

Discuss your specific requirements

Provide Usage Estimates

Share expected request volumes and patterns

Configuration

We’ll configure custom limits for your API keys

Testing

Test with your new limits before going live

Getting in Touch

If you have specific rate limit requirements or questions:

Email: support@instaview.sk
Enterprise customers: ask your account manager

Next Steps

Error Handling

Learn how to handle all API errors

Best Practices

Production integration patterns

Pagination

Efficiently paginate large result sets

Authentication

Understand API key authentication

Getting Started

Core Concepts

Resources

Advanced

Overview

How It Works

Response Headers

Rate Limit Response

Subscription Plan Limits

Endpoints With Lower Limits

Best Practices

Monitoring Your Usage

Handling Rate Limits

Custom Rate Limits

Getting in Touch

Next Steps

Error Handling

Best Practices

Pagination

Authentication

​Overview

​How It Works

​Response Headers

​Rate Limit Response

​Subscription Plan Limits

​Endpoints With Lower Limits

​Best Practices

​Monitoring Your Usage

​Handling Rate Limits

​Custom Rate Limits

​Getting in Touch

​Next Steps

Error Handling

Best Practices

Pagination

Authentication

Overview

How It Works

Response Headers

Rate Limit Response

Subscription Plan Limits

Endpoints With Lower Limits

Best Practices

Monitoring Your Usage

Handling Rate Limits

Custom Rate Limits

Getting in Touch

Next Steps