Clix Documentation

TL;DR

Rate Limit: 1,000 requests per second for Management API
Request Size: Maximum 10 MB per request
Error Response: Returns 429 Too Many Requests when limit is exceeded

The Clix API enforces rate limits to maintain service quality and fair resource allocation. Rate limiting ensures all projects can reliably use the platform without any single project impacting others.

How Rate Limiting Works

The Clix API uses a token bucket algorithm to manage request rates. Here’s how it works:

Token Bucket - Each project starts with a fixed number of tokens
Request Cost - Each API request consumes one token
Refill - The token bucket refills at regular intervals
Tracking - Rate limits are tracked per project using the X-Clix-Project-ID header

When your bucket has tokens available, requests succeed. When tokens are exhausted, requests receive a 429 Too Many Requests response until the bucket refills.

Rate Limit Policy

API Group	Limit	Time Window
Management Operations	1,000 requests	1 second

Management Operations include:

User management endpoints (create, update, delete users)
Message sending endpoints
Campaign triggering endpoints

Understanding Response Headers

Every API response includes rate limit information in the response headers:

Header	Description	Example
`X-RateLimit-Limit`	Total tokens in your bucket (requests per refill period)	`1000`
`X-RateLimit-Remaining`	Tokens available right now	`842`
`X-RateLimit-Reset`	Unix timestamp (seconds) when bucket refills	`1699617005`

These headers let you monitor your current token balance and plan your requests accordingly.

When You Hit a Rate Limit

Exceeding your rate limit results in a 429 Too Many Requests HTTP response:

{
  "error": "Too Many Requests"
}

What Happens Next

Your bucket is temporarily empty (no tokens available)
The bucket automatically refills after the interval specified in your rate limit
For Management API: The bucket refills every 1 second with 1,000 tokens
You can immediately retry after the refill time shown in X-RateLimit-Reset header

Retry-After Header

When rate limited, the response includes:

Retry-After: 1

This tells you how many seconds to wait before your next request will likely succeed.

Designing for Scale

Strategy 1: Exponential Backoff Retry Logic

When receiving a 429 response, automatically retry with increasing delays:

async function retryWithBackoff(makeRequest, maxRetries = 3) {
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await makeRequest();
    } catch (error) {
      if (error.status !== 429) throw error;

      lastError = error;
      if (attempt < maxRetries - 1) {
        // Exponential backoff: 1s, 2s, 4s, etc.
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }

  throw lastError;
}

Strategy 2: Request Batching and Sequencing

Group operations and spread them over time to avoid burst traffic:

// Batch user creation across time intervals
async function createUsersBatched(users, batchDelayMs = 100) {
  for (const user of users) {
    await api.createUser(user);
    await new Promise(resolve => setTimeout(resolve, batchDelayMs));
  }
}

// Call it
await createUsersBatched(['user1', 'user2', 'user3'], 50);

Strategy 3: Monitor Token Bucket State

Use response headers to track your token consumption and adjust pacing:

const response = await fetch(url, options);
const limit = parseInt(response.headers.get('X-RateLimit-Limit'), 10);
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'), 10);
const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'), 10);
const now = Math.floor(Date.now() / 1000);

console.log(`Tokens: ${remaining}/${limit}`);
console.log(`Refill in: ${resetTime - now} seconds`);

// If approaching empty bucket, slow down
if (remaining < 100) {
  console.log('Approaching rate limit - reducing request pace');
  // Implement adaptive throttling
}

This approach prevents hitting the limit by detecting high consumption patterns early.

Token Bucket Example

Here’s a visual representation of how tokens flow:

Time 0s:   [Bucket: 1000 tokens]
           Request 1 → [Remaining: 999 tokens]
           Request 2 → [Remaining: 998 tokens]
           ...
           Request 500 → [Remaining: 500 tokens]

Time 0.5s: [Bucket: 500 tokens] (still in current refill period)
           Request 501 → [Remaining: 499 tokens]
           Request 502 → [Remaining: 498 tokens]
           ...
           Request 1000 → RATE LIMITED (429)

Time 1s:   [Bucket: REFILLS to 1000 tokens]
           (Retry your request)
           Request 1000 → [Remaining: 999 tokens]

Calculating Request Rates

With a 1,000 token limit per 1 second refill:

Sustained rate: ~1,000 requests/second
Burst capacity: Up to 1,000 consecutive requests before rate limiting
Recovery time: 1 second for full bucket refill

Plan your integration accordingly:

For steady workloads: Distribute requests evenly across the 1-second window
For bursty workloads: Use retries and backoff when approaching the limit

Request Higher Limits

If your use case requires higher rate limits:

Email: [email protected]
Docs: https://docs.clix.so

Include your expected request patterns (steady vs. bursty) and peak throughput needs.

User Guide

Quick Start (Installation)

Essentials

Campaigns

Model Context Protocol

Agent Skills

Agent-to-Agent (A2A)

Integrations

API Reference

Troubleshooting

Security & Ops

Rate Limits

How Rate Limiting Works

Rate Limit Policy

Understanding Response Headers

When You Hit a Rate Limit

What Happens Next

Retry-After Header

Designing for Scale

Strategy 1: Exponential Backoff Retry Logic

Strategy 2: Request Batching and Sequencing

Strategy 3: Monitor Token Bucket State

Token Bucket Example

Calculating Request Rates

Request Higher Limits

​How Rate Limiting Works

​Rate Limit Policy

​Understanding Response Headers

​When You Hit a Rate Limit

​What Happens Next

​Retry-After Header

​Designing for Scale

​Strategy 1: Exponential Backoff Retry Logic

​Strategy 2: Request Batching and Sequencing

​Strategy 3: Monitor Token Bucket State

​Token Bucket Example

​Calculating Request Rates

​Request Higher Limits

How Rate Limiting Works

Rate Limit Policy

Understanding Response Headers

When You Hit a Rate Limit

What Happens Next

Retry-After Header

Designing for Scale

Strategy 1: Exponential Backoff Retry Logic

Strategy 2: Request Batching and Sequencing

Strategy 3: Monitor Token Bucket State

Token Bucket Example

Calculating Request Rates

Request Higher Limits