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

# Rate limiting

> Understand and handle API rate limits

# Rate limiting

The Tella API implements rate limiting to ensure fair usage and protect the service for all users.

## Current limits

| Limit               | Value    |
| ------------------- | -------- |
| Requests per minute | 100      |
| Scope               | Per user |

<Info>
  Rate limits are applied per user within an organization. All API keys created
  by the same user share the same rate limit.
</Info>

## Rate limit headers

Every API response includes headers with rate limit information:

| Header                  | Description                           | Example      |
| ----------------------- | ------------------------------------- | ------------ |
| `X-RateLimit-Limit`     | Maximum requests per window           | `100`        |
| `X-RateLimit-Remaining` | Remaining requests in current window  | `95`         |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets | `1704067200` |

### Example response headers

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
Content-Type: application/json
```

## Handling rate limits

### 429 Too Many Requests

When you exceed the rate limit, you'll receive a `429` status code:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "description": "Rate limit exceeded. Please retry after 45 seconds."
}
```

### Best practices

<AccordionGroup>
  <Accordion title="Check remaining requests">
    Monitor the `X-RateLimit-Remaining` header and slow down before hitting the limit.

    ```javascript theme={null}
    const response = await fetch('https://api.tella.com/v1/videos', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    const remaining = response.headers.get('X-RateLimit-Remaining');
    if (parseInt(remaining) < 10) {
      console.log('Approaching rate limit, slowing down...');
    }
    ```
  </Accordion>

  <Accordion title="Implement exponential backoff">
    When you receive a 429, wait before retrying with increasing delays:

    ```javascript theme={null}
    async function fetchWithRetry(url, options, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        const response = await fetch(url, options);

        if (response.status === 429) {
          const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
          console.log(`Rate limited. Waiting ${waitTime}ms...`);
          await new Promise(r => setTimeout(r, waitTime));
          continue;
        }

        return response;
      }
      throw new Error('Max retries exceeded');
    }
    ```
  </Accordion>

  <Accordion title="Use the reset timestamp">
    The `X-RateLimit-Reset` header tells you exactly when your limit resets:

    ```javascript theme={null}
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitMs = (parseInt(resetTime) * 1000) - Date.now();

    if (waitMs > 0) {
      console.log(`Waiting ${waitMs}ms until rate limit resets`);
      await new Promise(r => setTimeout(r, waitMs));
    }
    ```
  </Accordion>

  <Accordion title="Batch requests efficiently">
    Instead of making many small requests, use pagination efficiently:

    ```javascript theme={null}
    // Instead of fetching videos one by one
    // Fetch them in batches using the list endpoint
    let cursor = null;
    const allVideos = [];

    do {
      const url = cursor
        ? `https://api.tella.com/v1/videos?cursor=${cursor}`
        : 'https://api.tella.com/v1/videos';

      const response = await fetch(url, { headers });
      const data = await response.json();

      allVideos.push(...data.data);
      cursor = data.pagination.next_cursor;
    } while (cursor);
    ```
  </Accordion>
</AccordionGroup>

## Rate limit scope

Rate limits are calculated per user within an organization:

* All API keys created by the same user share the same 100 requests per minute limit
* Different users in the same organization have independent limits
* The limit applies across all endpoints

## Need higher limits?

If your use case requires higher rate limits, please [contact us](mailto:support@tella.com) to discuss your needs.