Copy page

Guides

Rate Limits & API Quotas

The Cineamo API implements rate limiting to ensure service stability and fair usage.

Rate Limit Overview

Rate limits restrict the number of API requests you can make within a time window.

Default Limits

• Authenticated requests: 1000 requests per hour
• Burst limit: 50 requests per minute
• Concurrent requests: 10 simultaneous requests

Rate Limit Headers

Every API response includes rate limit information in the headers:

Code
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1640995200

Header Descriptions

• X-RateLimit-Limit - Maximum requests allowed in the time window
• X-RateLimit-Remaining - Number of requests remaining
• X-RateLimit-Reset - Unix timestamp when the limit resets

Handling Rate Limits

Check Remaining Requests

Monitor the X-RateLimit-Remaining header to track your usage:

Code
const response = await fetch('https://api.cineamo.com/api/v1/movies', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const remaining = response.headers.get('X-RateLimit-Remaining');
console.log(`Requests remaining: ${remaining}`);

Handle 429 Responses

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

Code
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 300 seconds.",
    "retry_after": 300
  }
}

The Retry-After header indicates when you can retry:

Code
HTTP/1.1 429 Too Many Requests
Retry-After: 300
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

Implementing Backoff

Exponential Backoff Strategy

Code
async function makeRequestWithBackoff(url, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        headers: {
          'Authorization': `Bearer ${accessToken}`
        }
      });

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;

        console.log(`Rate limited. Retrying after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

Best Practices

Optimize Request Patterns

• Batch requests when possible
• Cache responses to reduce duplicate requests
• Use webhooks instead of polling
• Request only needed data using filters and field selection

Monitor Usage

Code
// Track rate limit status
function checkRateLimitStatus(response) {
  const limit = response.headers.get('X-RateLimit-Limit');
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');

  const resetDate = new Date(parseInt(reset) * 1000);
  const percentage = (remaining / limit) * 100;

  console.log(`Rate limit: ${remaining}/${limit} (${percentage.toFixed(1)}%)`);
  console.log(`Resets at: ${resetDate.toISOString()}`);

  // Alert if usage is high
  if (percentage < 10) {
    console.warn('⚠️ Rate limit nearly exceeded!');
  }
}

Distribute Load

• Spread requests over time
• Avoid burst patterns that quickly consume limits
• Implement request queuing for high-volume applications
• Use multiple API keys for different services (with approval)

Increasing Rate Limits

If your application requires higher rate limits:

1. Contact your Cineamo account manager
2. Provide use case and expected request volume
3. Discuss enterprise tier options

Rate Limit by Endpoint

Some endpoints have different rate limits:

Endpoint	Rate Limit	Notes
/api/v1/movies	Standard	1000/hour
/api/v1/orders	Standard	1000/hour
/api/v1/analytics	Reduced	100/hour
/api/v1/exports	Limited	10/hour

Check individual endpoint documentation for specific limits.