Skip to main content

​
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:
HeaderDescription
RateLimit-LimitMaximum number of requests allowed within the current window
RateLimit-RemainingNumber of requests you have left in the current window
RateLimit-ResetSeconds until the rate limit resets
retry-afterSeconds 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.