Documentation Index
Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Rate limits prevent abuse and ensure fair usage across all users.
Limits by Plan
Free Tier
- Requests: 100/hour
- Executions: 1,000/month
- Concurrent: 5
Pro Plan
- Requests: 1,000/hour
- Executions: 100,000/month
- Concurrent: 50
Enterprise
- Requests: Custom
- Executions: Custom
- Concurrent: Custom
Every API response includes rate limit headers:
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705315200
X-RateLimit-Retry-After: 3600
X-RateLimit-Limit - Total requests allowed per windowX-RateLimit-Remaining - Requests remaining in current windowX-RateLimit-Reset - Unix timestamp when limit resetsX-RateLimit-Retry-After - Seconds until you can retry (if rate limited)
Rate Limit Exceeded
When you exceed your rate limit:
Response (429)
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705315200
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please retry after 3600 seconds.",
"limit": 1000,
"reset": 1705315200,
"retryAfter": 3600
}
}
Handling in Code
async function executeWithRetry(ensemble, inputs) {
try {
return await conductor.execute(ensemble, inputs);
} catch (error) {
if (error.code === 'RATE_LIMIT_EXCEEDED') {
const retryAfter = error.retryAfter * 1000; // Convert to ms
console.log(`Rate limited. Retrying in ${retryAfter}ms`);
await sleep(retryAfter);
return await conductor.execute(ensemble, inputs);
}
throw error;
}
}
Best Practices
const response = await fetch(url, options);
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
const reset = parseInt(response.headers.get('X-RateLimit-Reset'));
if (remaining < 10) {
console.warn(`Only ${remaining} requests remaining until ${new Date(reset * 1000)}`);
}
2. Implement Backoff
async function withExponentialBackoff(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.code === 'RATE_LIMIT_EXCEEDED' && i < maxRetries - 1) {
const delay = Math.min(1000 * Math.pow(2, i), 30000);
await sleep(delay);
continue;
}
throw error;
}
}
}
3. Batch Requests
// Bad: Multiple sequential requests
for (const item of items) {
await conductor.execute('process-item', { item });
}
// Good: Single batched request
await conductor.execute('process-items', { items });
4. Cache Results
const cache = new Map();
async function executeWithCache(ensemble, inputs) {
const key = `${ensemble}:${JSON.stringify(inputs)}`;
if (cache.has(key)) {
return cache.get(key);
}
const result = await conductor.execute(ensemble, inputs);
cache.set(key, result);
return result;
}
5. Use Webhooks
// Bad: Poll for results
while (true) {
const status = await conductor.getExecution(executionId);
if (status.complete) break;
await sleep(1000); // Wastes rate limit
}
// Good: Use webhooks
await conductor.execute('ensemble', inputs, {
webhook: 'https://yourapp.com/webhook'
});
Rate Limit Tiers
Rate limits are calculated per:
- API Token: Each token has independent limits
- IP Address: Additional per-IP limits prevent abuse
- Time Window: Sliding 1-hour window
Concurrent Execution Limits
Maximum concurrent executions:
- Free: 5
- Pro: 50
- Enterprise: Custom
Handling Concurrency
const queue = new PQueue({ concurrency: 5 });
const results = await Promise.all(
items.map(item =>
queue.add(() => conductor.execute('process', { item }))
)
);
Monitoring Usage
Check Current Usage
curl https://your-worker.workers.dev/api/v1/usage \
-H "Authorization: Bearer ${API_TOKEN}"
{
"period": {
"start": 1705315200000,
"end": 1705318800000
},
"requests": {
"used": 234,
"limit": 1000,
"remaining": 766
},
"executions": {
"used": 1234,
"limit": 100000,
"remaining": 98766
}
}
Usage Dashboard
Monitor your usage through Cloudflare’s dashboard or implement custom analytics in your Conductor deployment.
Rate limits can be configured in your conductor.config.ts:
export default {
rateLimit: {
requests: 1000, // Per hour
window: 3600, // Seconds
concurrent: 50 // Max concurrent executions
}
}
Error Codes
RATE_LIMIT_EXCEEDED - Hourly limit exceededQUOTA_EXCEEDED - Monthly quota exceededCONCURRENT_LIMIT_EXCEEDED - Too many concurrent executions
Next Steps
