Rate Limits - Causeloop

The Causeloop API enforces a sliding-window rate limit per client IP. All requests — authenticated or not — count against the limit for the originating IP address.

Limits

Window	Max requests
60 seconds	600

The limit is applied per IP address (or the first value of X-Forwarded-For when the request passes through a proxy). Requests from different IPs are counted independently.

When Redis is configured (REDIS_URL), the limit is enforced across all API replicas using a shared fixed-window counter. Without Redis, the counter is per-process — a single IP hitting multiple replicas gets a higher effective limit. In production, configure Redis for consistent enforcement.

Rate limit response headers

Every response — including successful ones — carries two rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the 60-second window.
`X-RateLimit-Remaining`	Requests remaining in the current window.

When the limit is exceeded, the 429 response also includes:

Header	Description
`Retry-After`	Seconds to wait before the next window opens.
`X-RateLimit-Remaining`	Always `0` on a `429`.

429 response body

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

The 429 error body does not include a trace_id. Use the Retry-After header value, not a fixed delay, to determine how long to wait.

Handling rate limits

Read the X-RateLimit-Remaining header on every response. When it reaches zero or you receive a 429, back off and retry:

# Read headers from any response
curl -I https://api.causeloop.ai/v1/issues \
  -H "Authorization: Bearer $CAUSELOOP_TOKEN"

# HTTP/2 200
# x-ratelimit-limit: 600
# x-ratelimit-remaining: 598

async function callWithRetry(url, options, maxRetries = 4) {
  let delay = 1000;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const resp = await fetch(url, options);

    if (resp.status !== 429) return resp;

    const retryAfter = parseInt(resp.headers.get('Retry-After') ?? '1', 10);
    const jitter = Math.random() * 500;
    const wait = Math.max(retryAfter * 1000, delay) + jitter;

    console.warn(`Rate limited. Retrying in ${Math.round(wait)}ms (attempt ${attempt + 1})`);
    await new Promise(r => setTimeout(r, wait));
    delay *= 2; // exponential backoff
  }

  throw new Error('Rate limit retries exhausted');
}

// Usage
const resp = await callWithRetry(
  'https://api.causeloop.ai/v1/issues',
  { headers: { 'Authorization': `Bearer ${accessToken}` } },
);

import time
import random
import requests

def call_with_retry(url: str, max_retries: int = 4, **kwargs) -> requests.Response:
    delay = 1.0

    for attempt in range(max_retries + 1):
        resp = requests.get(url, **kwargs)

        if resp.status_code != 429:
            return resp

        retry_after = int(resp.headers.get('Retry-After', 1))
        jitter = random.random() * 0.5
        wait = max(retry_after, delay) + jitter

        print(f'Rate limited. Retrying in {wait:.1f}s (attempt {attempt + 1})')
        time.sleep(wait)
        delay *= 2  # exponential backoff

    raise RuntimeError('Rate limit retries exhausted')

# Usage
resp = call_with_retry(
    'https://api.causeloop.ai/v1/issues',
    headers={'Authorization': f'Bearer {access_token}'},
)

Best practices

Read X-RateLimit-Remaining proactively. If it’s low, slow down your request rate before hitting the limit. Implement exponential backoff with jitter. Start at the Retry-After value, then double the delay on each subsequent 429. Add random jitter (±500 ms) to avoid thundering-herd when multiple clients retry in sync. Avoid polling for status. Use the WebSocket stream for real-time updates — WebSocket messages do not count against REST rate limits. For endpoints that do require polling:

Endpoint	Safe poll interval
`GET /v1/reports/jobs/{id}`	Every 5 seconds
`GET /v1/exports/{id}`	Every 10 seconds
`GET /v1/me/notifications/unread-count`	Every 30 seconds
`GET /v1/shell/nav`	On app focus, not on a timer

Batch requests where possible. Filter lists server-side (?status=open) rather than fetching all records and filtering client-side.

​Limits

​Rate limit response headers

​429 response body

​Handling rate limits

​Best practices

Limits

Rate limit response headers

429 response body

Handling rate limits

Best practices