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
`RateLimit-Policy`	Named quota, request limit, and window in seconds	`"public-api";q=100;w=60`
`RateLimit`	Remaining quota and seconds until the window resets	`"public-api";r=95;t=42`
`X-RateLimit-Limit`	Maximum requests per window	`100`
`X-RateLimit-Remaining`	Remaining requests in the current window	`95`
`X-RateLimit-Reset`	Unix timestamp in milliseconds when the window resets	`1704067200000`

RateLimit-Policy and RateLimit use the structured HTTP rate-limit fields. The X-RateLimit-* headers remain available for compatibility with existing integrations.

Example response headers

HTTP/1.1 200 OK
RateLimit-Policy: "public-api";q=100;w=60
RateLimit: "public-api";r=95;t=42
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200000
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_limited",
  "message": "Too many requests",
  "docsUrl": "https://docs.tella.com/"
}

The response also includes Retry-After with the number of seconds to wait before retrying.

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

Respect retry timing

When you receive a REST API 429, respect Retry-After. For a retryable MCP error, wait for the duration in its text content before retrying:

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 retryAfter = Number(response.headers.get('Retry-After') ?? 1);
      const waitTime = retryAfter * 1000;
      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, in Unix epoch milliseconds:

const resetTime = response.headers.get('X-RateLimit-Reset');
const waitMs = parseInt(resetTime) - 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?