Rate limiting

The Tella public API and MCP server implement rate limiting to ensure fair usage and protect the service for all users.

Current limits

Limit	Value
Requests per minute	100
Scope	Per user within a workspace

All API keys and external MCP connections used by the same user in a workspace share one 100-request-per-minute limit.

Rate limit headers

Every REST 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/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
Content-Type: application/json

Handling rate limits

REST API requests

When a REST API request exceeds the limit, you’ll receive a 429 status code:

{
  "error": "rate_limit_exceeded",
  "description": "Rate limit exceeded. Please retry after 45 seconds."
}

MCP tool calls

When an MCP tool call exceeds the limit, the server returns a tool error instead of an HTTP 429 response. The result includes the number of seconds to wait and marks the error as retryable:

{
  "isError": true,
  "structuredContent": {
    "errorCode": "rate_limited",
    "retryable": true
  }
}

Wait for the duration in the first text content block before retrying the tool call.

Best practices

Check remaining requests

Monitor the X-RateLimit-Remaining header and slow down before hitting the limit.

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...');
}

Implement exponential backoff

When you receive a REST API 429 or a retryable MCP error, wait before retrying with increasing delays:

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');
}

Use the reset timestamp

The X-RateLimit-Reset header tells you exactly when your limit resets:

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));
}

Batch requests efficiently

Instead of making many small requests, use pagination efficiently:

// 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);

Rate limit scope

Rate limits are calculated per user within an organization:

All API keys and external MCP connections used by the same user share the same 100 requests per minute limit
Different users in the same organization have independent limits
REST API requests and MCP tool calls draw from the same limit

Need higher limits?

If your use case requires higher rate limits, please contact us to discuss your needs.

Getting Started

Guides

API Reference

Webhooks

Rate limiting

Rate limiting

Current limits

Rate limit headers

Example response headers

Handling rate limits

REST API requests

MCP tool calls

Best practices

Rate limit scope

Need higher limits?

​Rate limiting

​Current limits

​Rate limit headers

​Example response headers

​Handling rate limits

​REST API requests

​MCP tool calls

​Best practices

​Rate limit scope

​Need higher limits?

Rate limiting

Current limits

Rate limit headers

Example response headers

Handling rate limits

REST API requests

MCP tool calls

Best practices

Rate limit scope

Need higher limits?