> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cevoid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Learn about API rate limits and how to handle them gracefully

## 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.

<Note>
  Need a higher rate limit? [Contact support](mailto:support@cevoid.com) to discuss your requirements.
</Note>

***

## 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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;
}
```

***

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