This document describes the rate limiting policies for the Yemaya API.
Table of Contents#
- Overview
- Rate Limit Tiers
- Rate Limit Headers
- Endpoint-Specific Limits
- Handling Rate Limits
- 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:
{
"apiKey": {
"id": "key_abc123",
"rateLimit": {
"requests": 500,
"window": "minute"
}
}
}
Rate Limit Headers#
Every API response includes rate limit information in the headers:
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/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#
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#
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:
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:
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:
// 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:
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:
// 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:
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#
{
"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:
- Check your current usage in the dashboard
- Review your implementation for inefficiencies
- Consider upgrading your plan
- Contact api@yemaya.io for assistance