Eve library

Yemaya API Rate Limits

Other

Revision 1

On this page

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

Table of Contents#


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