Rate Limits

Overview

To ensure fair usage and maintain API stability for all users, the Cevoid API enforces rate limits on certain endpoints. When you exceed the rate limit, the API returns a 429 Too Many Requests response.

Default Rate Limit

The default rate limit is 5 requests per second for most endpoints. Some endpoints may have different limits based on their resource requirements.

Need a higher rate limit? Contact support to discuss your requirements.

Rate Limit Headers

Every API response includes headers that help you monitor your usage. These headers follow the IETF RateLimit header fields standard:

Header	Description
`RateLimit-Limit`	Maximum number of requests allowed within the current window
`RateLimit-Remaining`	Number of requests you have left in the current window
`RateLimit-Reset`	Seconds until the rate limit resets
`retry-after`	Seconds to wait before making another request (only on 429 responses)

Handling Rate Limit Errors

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

{
  "error": "Rate limit exceeded. Try again in 1 second."
}

The retry-after header tells you exactly how long to wait before retrying.

Best Practices

1. Monitor Rate Limit Headers

Check the RateLimit-Remaining header to avoid RateLimit-Resetit:

const response = await fetch('https://api.cevoid.com/v1/posts', {
  headers: { 'x-api-key': 'your-api-key' }
});

const remaining = response.headers.get('RateLimit-Remaining');
const reset = response.headers.get('RateLimit-Reset');

if (parseInt(remaining) < 2) {
  console.log(`Low on requests. Resets in ${reset} seconds.`);
}

2. Implement Retry Logic

Handle rate limit errors gracefully with exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('retry-after') || '1');
      console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

3. Use Caching

Reduce API calls by caching responses when possible:

const cache = new Map();
const CACHE_TTL = 60000; // 1 minute

async function getCachedPosts(galleryId) {
  const cacheKey = `posts-${galleryId}`;
  const cached = cache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const response = await fetch(`https://api.cevoid.com/v1/posts?galleryId=${galleryId}`, {
    headers: { 'x-api-key': 'your-api-key' }
  });
  
  const data = await response.json();
  cache.set(cacheKey, { data, timestamp: Date.now() });
  
  return data;
}

Rate limits are applied per API key. Sharing an API key across multiple applications will result in shared rate limits.

Introduction

Core Concepts

Endpoints

Overview

Default Rate Limit

Rate Limit Headers

Handling Rate Limit Errors

Best Practices

1. Monitor Rate Limit Headers

2. Implement Retry Logic

3. Use Caching

​Overview

​Default Rate Limit

​Rate Limit Headers

​Handling Rate Limit Errors

​Best Practices

​1. Monitor Rate Limit Headers

​2. Implement Retry Logic

​3. Use Caching

Overview

Default Rate Limit

Rate Limit Headers

Handling Rate Limit Errors

Best Practices

1. Monitor Rate Limit Headers

2. Implement Retry Logic

3. Use Caching