Rate Limits

Understand API rate limits and best practices for staying within limits.

Overview

The Deepns API implements rate limiting to ensure fair usage and system stability. Rate limits apply per API key and are reset on a rolling window basis.

Rate Limit Tiers

Free Plan

  • 100 requests per minute
  • 5,000 requests per hour
  • 50,000 requests per day

Professional Plan

  • 500 requests per minute
  • 25,000 requests per hour
  • 250,000 requests per day

Enterprise Plan

  • 2,000 requests per minute
  • 100,000 requests per hour
  • 1,000,000 requests per day
  • Custom limits available on request

Rate Limit Headers

Every API response includes these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1648035600
Header Description
X-RateLimit-Limit Maximum requests allowed in window
X-RateLimit-Remaining Requests remaining in current window
X-RateLimit-Reset Unix timestamp when limit resets

Rate Limit Exceeded

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

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}

The Retry-After header indicates how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Reset: 1648035600

Best Practices

1. Respect Rate Limits

Check headers and don’t send requests when limit is reached:

async function makeRequest(url, options) {
  const response = await fetch(url, options);

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

  if (remaining === 0) {
    const waitTime = (reset * 1000) - Date.now();
    console.log(`Rate limit reached. Waiting ${waitTime}ms`);
    await sleep(waitTime);
  }

  return response;
}

2. Implement Exponential Backoff

Retry with increasing delays:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

3. Use Batch Endpoints

Send multiple events in one request:

// ❌ Bad: Multiple requests
for (const event of events) {
  await sendEvent(event); // 100 requests
}

// ✅ Good: Single batch request
await sendEventsBatch(events); // 1 request

4. Cache Data

Cache responses to reduce API calls:

const cache = new Map();

async function getCachedData(key, ttl = 60000) {
  if (cache.has(key)) {
    const { data, timestamp } = cache.get(key);
    if (Date.now() - timestamp < ttl) {
      return data;
    }
  }

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

5. Queue Requests

Implement a request queue:

class RequestQueue {
  constructor(maxPerMinute) {
    this.queue = [];
    this.maxPerMinute = maxPerMinute;
    this.lastReset = Date.now();
    this.count = 0;
  }

  async enqueue(fn) {
    // Reset counter if minute has passed
    if (Date.now() - this.lastReset > 60000) {
      this.count = 0;
      this.lastReset = Date.now();
    }

    // Wait if limit reached
    if (this.count >= this.maxPerMinute) {
      const waitTime = 60000 - (Date.now() - this.lastReset);
      await sleep(waitTime);
      this.count = 0;
      this.lastReset = Date.now();
    }

    this.count++;
    return await fn();
  }
}

Monitoring Usage

Check Current Usage

Get your current rate limit status:

curl https://api.deepns.com/rate-limit \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "limits": {
    "minute": {
      "limit": 500,
      "remaining": 487,
      "reset": 1648035600
    },
    "hour": {
      "limit": 25000,
      "remaining": 24850,
      "reset": 1648037400
    },
    "day": {
      "limit": 250000,
      "remaining": 248500,
      "reset": 1648122000
    }
  },
  "plan": "professional"
}

Usage Dashboard

Monitor your API usage in the dashboard:

  1. Go to Settings > API Usage
  2. View real-time rate limit status
  3. See historical usage patterns
  4. Set up usage alerts

Usage Alerts

Configure alerts for high usage:

  1. Navigate to Settings > Alerts
  2. Create “API Usage Alert”
  3. Set threshold (e.g., 80% of limit)
  4. Choose notification method

Increasing Limits

Need higher limits?

Upgrade Your Plan

Higher-tier plans have increased limits:

  • Professional: 5x Free plan limits
  • Enterprise: 20x Free plan limits

Request Custom Limits

For enterprise customers:

  1. Contact sales at sales@deepns.com
  2. Provide use case and estimated volume
  3. Get custom limit approval
  4. Limits updated within 24 hours

Endpoint-Specific Limits

Some endpoints have stricter limits:

Endpoint Limit
POST /events Standard rate limits
POST /events/batch 1/10 of standard limits (max 100 events per batch)
GET /events Standard rate limits
GET /analytics 50 requests per minute

Avoiding Rate Limits

Client-Side Tracking

Use client-side JavaScript SDK:

  • No rate limits for pageview tracking
  • Events sent directly from browser
  • API key usage minimized
// Client-side (no rate limits)
deepns.track('page_view');

Webhooks

Use webhooks instead of polling:

  • Configure webhooks in dashboard
  • Receive real-time updates
  • No API calls needed

WebSocket Connection

Use WebSocket for real-time data:

const ws = new WebSocket('wss://api.deepns.com/stream');

ws.on('message', (data) => {
  // Receive real-time events
});

Next Steps

Documentation