Rate limits

KrosAI applies rate limits to ensure fair usage and platform stability.

Limits by Plan

Plan	Requests/Second	Requests/Day	Concurrent Calls
Free	10	1,000	1
Pro	50	50,000	10
Business	200	500,000	50
Enterprise	Custom	Custom	Unlimited

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704891600

Header	Description
X-RateLimit-Limit	Maximum requests per second
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Rate Limit Response

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 1.5
}

The Retry-After header indicates seconds to wait:

Retry-After: 1.5

Endpoint-Specific Limits

Some endpoints have additional limits:

Endpoint	Limit	Notes
POST /outbound-calls	10/sec	Per organization
POST /phone-numbers	5/sec	KYC required
GET /calls	100/sec	Pagination recommended
POST /webhooks	10/sec	Per organization

Concurrent Call Limits

Outbound calls have concurrency limits:

Plan	Concurrent Outbound
Free	1
Pro	10
Business	50
Enterprise	Unlimited

Exceeding the concurrent call limit returns:

{
  "error": "Maximum concurrent calls reached",
  "code": "CONCURRENT_LIMIT_EXCEEDED",
  "current": 10,
  "limit": 10
}

Best Practices

Implement Exponential Backoff

exponential-backoff.ts

async function makeRequestWithRetry(
  fn: () => Promise<Response>,
  maxRetries = 3
): Promise<Response> {
  let lastError: Error | null = null;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fn();
      
      if (response.status === 429) {
        const retryAfter = parseFloat(
          response.headers.get('Retry-After') || '1'
        );
        await sleep(retryAfter * 1000 * Math.pow(2, attempt));
        continue;
      }
      
      return response;
    } catch (error) {
      lastError = error as Error;
    }
  }
  
  throw lastError || new Error('Max retries exceeded');
}

Use Batch Operations

batch-requests.ts

// ❌ Avoid: Multiple individual requests
for (const number of numbers) {
  await fetch(`/phone-numbers/${number.id}`);
}

// ✅ Better: Single batch request
await fetch('/phone-numbers', {
  params: { ids: numbers.map(n => n.id).join(',') }
});

Cache Responses

cache-example.ts

const CACHE_TTL = 60 * 1000; // 1 minute

async function getPhoneNumbers() {
  const cached = cache.get('phone_numbers');
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const response = await fetch('/phone-numbers');
  const data = await response.json();
  
  cache.set('phone_numbers', { data, timestamp: Date.now() });
  return data;
}

Monitor Usage

log-rate-limits.ts

function logRateLimits(response: 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 Limit: ${remaining}/${limit} (resets: ${reset})`);
  
  if (parseInt(remaining || '0') < 10) {
    console.warn('Approaching rate limit!');
  }
}

Queue Outbound Calls

call-queue.ts

class CallQueue {
  private queue: CallRequest[] = [];
  private active = 0;
  private maxConcurrent = 10;
  
  async add(request: CallRequest) {
    this.queue.push(request);
    this.process();
  }
  
  private async process() {
    while (this.queue.length > 0 && this.active < this.maxConcurrent) {
      const request = this.queue.shift()!;
      this.active++;
      
      try {
        await this.initiateCall(request);
      } finally {
        this.active--;
        this.process();
      }
    }
  }
}

Requesting Higher Limits

Need higher limits? Contact us:

• Pro/Business: Upgrade to a higher plan

• Enterprise: Custom limits available

Email [e-mail] with:

1

Organization ID

Provide your organization ID.

2

Current usage patterns

Describe your current usage patterns (traffic, peak times, typical requests).

3

Required limits

Specify the limits you need (requests/sec, requests/day, concurrency).

4

Use case description

Explain the use case and why higher limits are required.

Next Steps

• Error Codes - Handle errors properly

• SDKs - Use official SDKs with built-in retry logic