# Yemaya API Rate Limits

This document describes the rate limiting policies for the Yemaya API.

## Table of Contents

- [Overview](#overview)
- [Rate Limit Tiers](#rate-limit-tiers)
- [Rate Limit Headers](#rate-limit-headers)
- [Endpoint-Specific Limits](#endpoint-specific-limits)
- [Handling Rate Limits](#handling-rate-limits)
- [Best Practices](#best-practices)

---

## Overview

Rate limiting protects the Yemaya API from abuse and ensures fair usage for all users. When you exceed a rate limit, the API returns a `429 Too Many Requests` response.

### How It Works

- Rate limits are applied **per user** for authenticated requests
- Rate limits are applied **per IP address** for unauthenticated requests
- Limits reset on a **sliding window** basis (not fixed intervals)
- Different endpoints may have different limits

---

## Rate Limit Tiers

### Free Tier

| Limit Type | Requests | Time Window |
|------------|----------|-------------|
| API requests | 60 | per minute |
| AI generations | 10 | per hour |
| File uploads | 20 | per hour |
| WebSocket messages | 100 | per minute |

### Pro Tier

| Limit Type | Requests | Time Window |
|------------|----------|-------------|
| API requests | 1,000 | per minute |
| AI generations | 100 | per hour |
| File uploads | 200 | per hour |
| WebSocket messages | 1,000 | per minute |

### Enterprise Tier

| Limit Type | Requests | Time Window |
|------------|----------|-------------|
| API requests | 10,000 | per minute |
| AI generations | 1,000 | per hour |
| File uploads | Unlimited | - |
| WebSocket messages | 10,000 | per minute |

### API Key Limits

API keys inherit the rate limits of their associated account, with optional custom limits:

```json
{
  "apiKey": {
    "id": "key_abc123",
    "rateLimit": {
      "requests": 500,
      "window": "minute"
    }
  }
}
```

---

## Rate Limit Headers

Every API response includes rate limit information in the headers:

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705318260
X-RateLimit-Policy: 1000;w=60
```

### Header Descriptions

| Header | Description | Example |
|--------|-------------|---------|
| `X-RateLimit-Limit` | Maximum requests allowed in the window | `1000` |
| `X-RateLimit-Remaining` | Requests remaining in current window | `999` |
| `X-RateLimit-Reset` | Unix timestamp when the window resets | `1705318260` |
| `X-RateLimit-Policy` | Rate limit policy (`limit;w=window_seconds`) | `1000;w=60` |

### Rate Limited Response

When you exceed the rate limit:

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705318260
Retry-After: 45

{
  "type": "https://api.yemaya.io/problems/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 45 seconds.",
  "extensions": {
    "limit": 1000,
    "remaining": 0,
    "resetAt": "2024-01-15T10:31:00.000Z",
    "retryAfter": 45
  }
}
```

---

## Endpoint-Specific Limits

Some endpoints have additional rate limits:

### Authentication

| Endpoint | Limit | Window | Notes |
|----------|-------|--------|-------|
| `POST /v1/auth/login` | 10 | per minute | Per IP, prevents brute force |
| `POST /v1/auth/register` | 5 | per minute | Per IP |
| `POST /v1/auth/forgot-password` | 3 | per hour | Per email |
| `POST /v1/auth/verify-email` | 10 | per hour | Per user |

### Capability Domains

| Endpoint | Limit | Window | Notes |
|----------|-------|--------|-------|
| `POST /v1/capabilities/isis/*` | 10 | per minute | Expensive generation requests |
| `POST /v1/capabilities/bellona/*` | 5 | per minute | Expensive render and engine-sync requests |

### File Operations

| Endpoint | Limit | Window | Notes |
|----------|-------|--------|-------|
| `POST /v1/assets` | See tier | per hour | Upload limit |
| `GET /v1/assets/:id/download` | 100 | per minute | Download limit |

### Search

| Endpoint | Limit | Window | Notes |
|----------|-------|--------|-------|
| `GET /v1/search` | 100 | per minute | Complex queries |
| `GET /v1/search/suggestions` | 200 | per minute | Lightweight |

### Webhooks

| Endpoint | Limit | Window | Notes |
|----------|-------|--------|-------|
| `POST /v1/webhooks/:id/test` | 10 | per hour | Per webhook |

### Batch Operations

| Endpoint | Limit | Window | Notes |
|----------|-------|--------|-------|
| `POST /v1/*/batch` | 10 | per minute | Batch endpoints |

---

## Handling Rate Limits

### Basic Retry Logic

```javascript
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    // Get retry delay from header
    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : 1000;

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

  throw new Error('Max retries exceeded due to rate limiting');
}
```

### Python Example

```python
import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get('Retry-After', 1))
        print(f"Rate limited. Retrying in {retry_after}s...")
        time.sleep(retry_after)

    raise Exception("Max retries exceeded due to rate limiting")
```

### Exponential Backoff

For more robust handling, use exponential backoff:

```javascript
async function fetchWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return response;
    }

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const baseDelay = retryAfter
        ? parseInt(retryAfter, 10) * 1000
        : 1000;

      // Add jitter to prevent thundering herd
      const jitter = Math.random() * 1000;
      const delay = baseDelay + jitter;

      console.log(`Rate limited. Attempt ${attempt + 1}/${maxRetries}. Waiting ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    // For other errors, use exponential backoff
    if (response.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}
```

### Proactive Rate Limit Management

Monitor headers to avoid hitting limits:

```javascript
class RateLimitManager {
  constructor() {
    this.remaining = Infinity;
    this.resetAt = 0;
  }

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

    if (remaining) this.remaining = parseInt(remaining, 10);
    if (reset) this.resetAt = parseInt(reset, 10) * 1000;
  }

  async waitIfNeeded() {
    if (this.remaining <= 1) {
      const waitTime = Math.max(0, this.resetAt - Date.now());
      console.log(`Approaching rate limit. Waiting ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
  }

  async fetch(url, options) {
    await this.waitIfNeeded();
    const response = await fetch(url, options);
    this.update(response);
    return response;
  }
}

const rateLimiter = new RateLimitManager();
const response = await rateLimiter.fetch('/v1/projects', { headers });
```

---

## Best Practices

### 1. Monitor Rate Limit Headers

Always check the `X-RateLimit-Remaining` header and slow down before hitting limits.

### 2. Use Bulk/Batch Endpoints

Instead of making individual requests:

```javascript
// Bad: 100 individual requests
for (const id of projectIds) {
  await fetch(`/v1/projects/${id}`);
}

// Good: 1 batch request
await fetch('/v1/projects/batch', {
  method: 'POST',
  body: JSON.stringify({ ids: projectIds })
});
```

### 3. Cache Responses

Cache responses to reduce API calls:

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

async function getCachedProject(id) {
  const cached = cache.get(id);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const response = await fetch(`/v1/projects/${id}`);
  const data = await response.json();

  cache.set(id, { data, timestamp: Date.now() });
  return data;
}
```

### 4. Use Webhooks Instead of Polling

Instead of polling for updates:

```javascript
// Bad: Polling every 5 seconds
setInterval(async () => {
  await fetch('/v1/projects/123');
}, 5000);

// Good: Use webhooks
// Subscribe once, receive updates automatically
```

### 5. Implement Request Queuing

Queue requests to control rate:

```javascript
class RequestQueue {
  constructor(requestsPerSecond) {
    this.queue = [];
    this.interval = 1000 / requestsPerSecond;
    this.lastRequest = 0;
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;

    while (this.queue.length > 0) {
      const timeSinceLast = Date.now() - this.lastRequest;
      if (timeSinceLast < this.interval) {
        await new Promise(r => setTimeout(r, this.interval - timeSinceLast));
      }

      const { requestFn, resolve, reject } = this.queue.shift();
      this.lastRequest = Date.now();

      try {
        resolve(await requestFn());
      } catch (error) {
        reject(error);
      }
    }

    this.processing = false;
  }
}

// Usage: 10 requests per second max
const queue = new RequestQueue(10);
await queue.add(() => fetch('/v1/projects'));
```

### 6. Request Rate Limit Increases

If you consistently hit rate limits, contact us for a limit increase:

- **Pro users:** Upgrade to Enterprise
- **Enterprise users:** Contact your account manager
- **Everyone:** Email api@yemaya.io with your use case

---

## Quotas vs Rate Limits

Rate limits and quotas are different:

| Aspect | Rate Limit | Quota |
|--------|------------|-------|
| Time frame | Minutes/hours | Monthly |
| Purpose | Prevent abuse | Usage allocation |
| Reset | Sliding window | Monthly |
| HTTP Status | 429 | 402 |

### Quota Example

```json
{
  "type": "https://api.yemaya.io/problems/quota-exceeded",
  "title": "Quota Exceeded",
  "status": 402,
  "detail": "Monthly AI generation quota exceeded",
  "extensions": {
    "quotaType": "ai_generations",
    "limit": 1000,
    "used": 1000,
    "resetAt": "2024-02-01T00:00:00.000Z"
  }
}
```

---

## FAQ

### Q: What happens when I hit a rate limit?

A: You'll receive a `429 Too Many Requests` response. Wait for the time indicated in the `Retry-After` header before retrying.

### Q: Do rate limits apply to all HTTP methods?

A: Yes, all API requests count toward your rate limit, including GET, POST, PUT, PATCH, and DELETE.

### Q: Are WebSocket messages rate limited?

A: Yes, WebSocket messages have separate rate limits. If exceeded, the connection may be throttled or closed.

### Q: Do failed requests count toward the limit?

A: Yes, all requests count toward your rate limit, regardless of the response status.

### Q: Can I get higher limits?

A: Yes! Upgrade your plan or contact us for Enterprise pricing with custom limits.

---

## Support

If you're experiencing rate limit issues:

1. Check your current usage in the dashboard
2. Review your implementation for inefficiencies
3. Consider upgrading your plan
4. Contact api@yemaya.io for assistance
