Rate Limits

Atlas API rate limits, headers, and how to handle 429 responses.

Rate Limit Summary

Endpoint	Limit	Window
POST /api/v1/* (single events)	1,000 req/s	Per API key
POST /api/v1/*/batch	100 req/s	Per API key
POST /v1/events	500 req/s	Per JWT token
POST /v1/events/batch	50 req/s	Per JWT token
Backend API (/v1/*, /auth/*)	60 req/min	Per user

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1710161400
Retry-After: 1     # Only present on 429 responses

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

Handling 429 Responses

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

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 1 second.",
    "retry_after": 1
  }
}

Exponential Backoff Pattern

async function callWithBackoff(fn, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fn();

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
    const jitter = Math.random() * 1000; // Add jitter to avoid thundering herd
    const delay = (retryAfter * 1000) * Math.pow(2, attempt) + jitter;

    console.warn(`Rate limited. Retrying in ${delay}ms (attempt ${attempt + 1})`);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

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

High-Volume Integration Patterns

Pattern 1 — Use Batch Endpoints

If you’re hitting single-event rate limits, switch to batch:

Individual calls: 1,000 events → 1,000 requests (hits limit)
Batch calls:      1,000 events → 2 requests (well within limit)

Pattern 2 — Queue and Flush

Buffer events in memory and flush in batches:

class AtlasBatcher {
  constructor(apiKey, flushInterval = 1000, maxBatchSize = 500) {
    this.queue = [];
    this.apiKey = apiKey;
    setInterval(() => this.flush(), flushInterval);
    this.maxBatchSize = maxBatchSize;
  }

  track(event) {
    this.queue.push(event);
    if (this.queue.length >= this.maxBatchSize) {
      this.flush();
    }
  }

  async flush() {
    if (this.queue.length === 0) return;
    const batch = this.queue.splice(0, this.maxBatchSize);
    await fetch('https://events.atlas.io/api/v1/sport/batch', {
      method: 'POST',
      headers: { 'X-API-Key': this.apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ events: batch }),
    });
  }
}

Pattern 3 — Multiple API Keys

For very high-volume operations, you can create multiple API keys (one per service/worker) to distribute load across separate rate limit buckets.

Contact [e-mail] if you need higher rate limits for your use case. Enterprise plans include custom limits.