> ## Documentation Index
> Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understand API rate limits and how to handle them gracefully

## Overview

TimelinesAI APIs enforce rate limits to ensure fair usage and platform stability for all users. Requests that exceed the rate limit will receive an HTTP `429 Too Many Requests` response.

## Rate Limit Details

| Parameter | Value |
| - | - |
| **Rate limit** | 30 requests per second |
| **Per** | IP address |
| **Burst allowance** | 10 additional requests |
| **Exceeded response** | HTTP `429 Too Many Requests` |

> [!NOTE]
>
> The rate limit applies **per IP address**, not per API token. If you have multiple integrations running from the same IP, they share the same rate limit budget.

## How It Works

Incoming requests are evaluated against a limit of **30 requests per second** per IP address. When you exceed this rate:

1. Up to **10 additional requests** are queued (burst allowance) and processed once capacity becomes available.
2. Any requests beyond the burst allowance are immediately rejected with an HTTP `429` status code.

```
Normal traffic:     ✅ ≤ 30 req/s  → Processed immediately
Burst traffic:      ⏳ 31–40 req/s → Queued and processed shortly
Over limit:         ❌ > 40 req/s  → Rejected with HTTP 429
```

## Handling Rate Limits

When you receive a `429` response, implement an **exponential backoff** strategy to retry requests:

```javascript JavaScript theme={null}
async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s, 8s, 16s
      console.warn(`Rate limited. Retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

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

```python Python theme={null}
import time
import requests

def request_with_retry(url, headers=None, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            delay = (2 ** attempt)  # 1s, 2s, 4s, 8s, 16s
            print(f"Rate limited. Retrying in {delay}s...")
            time.sleep(delay)
            continue

        return response

    raise Exception("Max retries exceeded")
```

```bash cURL theme={null}
# Example 429 response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after a short delay."
}
```

## Best Practices

> [accordion] Spread requests over time
>
> Instead of sending bulk requests all at once, distribute them evenly. For example, if you need to send 100 messages, space them out at \~30 per second rather than sending all 100 simultaneously.

> [accordion] Implement exponential backoff
>
> When you receive a `429` response, wait progressively longer between retries — e.g., 1 second, then 2, then 4. This prevents a "thundering herd" effect when rate limits lift.

> [accordion] Use queuing for bulk operations
>
> For batch processing (e.g., sending messages to many contacts), implement a client-side queue that respects the 30 req/s limit. Process items from the queue at a controlled rate.

> [accordion] Monitor your usage
>
> Track your request rates in your application logs. If you're consistently hitting rate limits, consider optimizing your integration to make fewer, more targeted API calls.

> [!WARNING]
>
> Repeatedly exceeding rate limits without implementing backoff may result in temporarily extended throttling for your IP address.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.