Skip to main content

Request Limits

Eventicat implements rate limits to ensure fair usage and maintain service quality for all users.

Rate Limits​

API Request Rate​

5 requests per second per user account

This limit applies to all API endpoints, including event submission (/api/event).

How It Works​

The rate limit uses a sliding window algorithm:

  • Limit resets continuously over a 1-second window
  • If you exceed the limit, requests are rejected until the window slides forward
  • The limit applies per user account (not per aggregator)

Rate Limit Headers​

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1640995201
HeaderDescription
X-RateLimit-LimitTotal requests allowed per second
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the limit resets

Rate Limit Exceeded Response​

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

{
  "error": "Rate limit exceeded",
  "limit": 5,
  "remaining": 0,
  "resetTime": 1640995201
}

What to do:

  1. Wait until the reset time
  2. Implement exponential backoff in your code
  3. Reduce request frequency
  4. Contact us if you need higher limits

Other Limits​

Event Name Length​

Event names must be URL-compatible and not cause HTTP 414 (URL Too Long) errors.

Practical limit: Keep event names under 200 characters.

Tag Limits​

  • Maximum tag key length: 100 characters
  • Valid characters: Letters, numbers, hyphens, underscores (after normalization)

Tags exceeding the length limit are silently ignored. There is no enforced limit on the number of tags per event.

Aggregator Limits​

There are no hard limits on the number of aggregators you can create per account.

Best Practices​

1. Batch Events When Possible​

Instead of sending events immediately, batch them:

// Instead of this (5+ requests/sec):
for (const event of events) {
  await sendEvent(event.name);
}

// Do this (controlled rate):
const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));

for (const event of events) {
  await sendEvent(event.name);
  await delay(250); // 4 requests/second
}

2. Implement Retry with Exponential Backoff​

Handle rate limit errors gracefully:

async function sendEventWithRetry(name, tags, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        `https://app.eventicat.com/api/event?_id=${AGGREGATOR_ID}`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ name, ...tags })
        }
      );

      if (response.status === 429) {
        // Rate limited - wait and retry
        const data = await response.json();
        const waitTime = (data.resetTime * 1000) - Date.now();
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      // Exponential backoff
      await new Promise(resolve =>
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
}

3. Monitor Rate Limit Headers​

Check remaining requests before sending:

async function sendEvent(name, tags) {
  const response = await fetch(/* ... */);

  const remaining = parseInt(
    response.headers.get('X-RateLimit-Remaining')
  );

  if (remaining < 2) {
    console.warn('Approaching rate limit, slowing down...');
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  return response.json();
}

4. Use Queues for High-Volume Applications​

For applications with bursts of events:

class EventQueue {
  constructor() {
    this.queue = [];
    this.processing = false;
  }

  add(name, tags) {
    this.queue.push({ name, tags });
    if (!this.processing) {
      this.process();
    }
  }

  async process() {
    this.processing = true;

    while (this.queue.length > 0) {
      const event = this.queue.shift();
      await sendEvent(event.name, event.tags);

      // Wait 250ms between requests (4/sec, safe margin)
      await new Promise(resolve => setTimeout(resolve, 250));
    }

    this.processing = false;
  }
}

const eventQueue = new EventQueue();

// Usage
eventQueue.add('user_signup', { 'env-production': true });

Need Higher Limits?​

If your application requires higher rate limits, we'd love to hear from you!

Contact Us​

Please include:

  1. Your account email
  2. Current usage patterns
  3. Expected request volume
  4. Use case description

We'll work with you to find a solution that meets your needs.

Monitoring Your Usage​

Currently, there's no built-in usage dashboard. To monitor your API usage:

  1. Track rate limit headers in your application
  2. Log 429 responses to identify when you hit limits
  3. Monitor error rates in your application logs

A usage dashboard is planned for a future release.

Next Steps​