Documentation Index
Fetch the complete documentation index at: https://docs.cloro.dev/llms.txt
Use this file to discover all available pages before exploring further.
The cloro API uses a credit-based billing system with concurrency limits.
Credits system
How credits work
- Each API request consumes credits based on the endpoint and features used
- Credits are deducted from your account balance when requests complete successfully
- Failed requests (4xx errors) don’t consume credits
- Credit information is included in response headers
- Sync monitor requests (
/v1/monitor/*) include a +2 credit surcharge on top of base and feature costs (see Providers for details)
- See Request & Response for endpoint pricing details
- For batch requests, credits are tracked per task within the batch. Each task’s result includes its own
creditsToCharge and creditsCharged values
cloro uses different response headers depending on the endpoint type:
All endpoints (/v1/*): Rate limit information
Monitor endpoints (/v1/monitor/*): Credit and concurrency information (in addition to rate limits)
| Header | Description |
|---|
X-RateLimit-Limit | Maximum requests per second allowed (500) |
X-RateLimit-Remaining | Remaining requests available in this second |
| Header | Description |
|---|
X-Credits-Remaining | Number of credits remaining in your account |
X-Credits-Charged | Number of credits charged for this request |
| Header | Description |
|---|
X-Concurrent-Limit | Maximum number of concurrent requests allowed |
X-Concurrent-Current | Current number of concurrent requests |
X-Concurrent-Remaining | Number of remaining concurrent slots available |
Concurrency limits
How concurrency works
- Concurrency limits control how many requests you can run simultaneously
- Limits are per API key/account
- Exceeding limits results in 429 Too Many Requests errors
- Limits keep the service stable for all users
Example scenario
Request 1: X-Concurrent-Limit: 10
Request 1: X-Concurrent-Current: 1
Request 1: X-Concurrent-Remaining: 9
Request 2: X-Concurrent-Limit: 10
Request 2: X-Concurrent-Current: 2
Request 2: X-Concurrent-Remaining: 8
Handling concurrency limits
When you receive a 429 error:
{
"error": {
"code": "CONCURRENT_LIMIT_EXCEEDED",
"message": "Concurrent limit exceeded",
"details": {
"limit": 10
},
"timestamp": "2025-01-15T12:00:00.000Z"
}
}
async function makeRequestWithRetry(requestFn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await requestFn();
} catch (error) {
if (error.status === 429 && i < maxRetries - 1) {
const delay = Math.pow(2, i) * 1000; // Exponential backoff
await new Promise((resolve) => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
}
Monitoring usage
Track credit consumption
function trackCredits(response) {
const creditsRemaining = response.headers["x-credits-remaining"];
const creditsCharged = response.headers["x-credits-charged"];
console.log(`Credits charged: ${creditsCharged}`);
console.log(`Credits remaining: ${creditsRemaining}`);
// Alert if running low
if (creditsRemaining < 100) {
console.warn("Low credit balance. Consider topping up");
}
}
Monitor concurrency
function monitorConcurrency(response) {
const limit = parseInt(response.headers["x-concurrent-limit"]);
const current = parseInt(response.headers["x-concurrent-current"]);
const remaining = parseInt(response.headers["x-concurrent-remaining"]);
const usagePercent = (current / limit) * 100;
if (usagePercent > 80) {
console.warn(`High concurrency usage: ${usagePercent.toFixed(1)}%`);
}
}
Monitor rate limits (all endpoints)
function monitorRateLimits(response) {
const limit = parseInt(response.headers["x-ratelimit-limit"]);
const remaining = parseInt(response.headers["x-ratelimit-remaining"]);
const usagePercent = ((limit - remaining) / limit) * 100;
console.log(`Rate limit: ${remaining}/${limit} requests remaining this second`);
if (remaining < 50) {
console.warn(`Rate limit nearly exceeded. Consider throttling requests.`);
}
}
Getting help
Credit issues
- Low balance: Top up your account via your dashboard
- Unexpected charges: Check request logs and verify which features were enabled
- Billing questions: Contact support with request IDs
Limit issues
- Frequent 429 errors: Consider implementing request queuing or throttling
- Rate limit issues: Monitor
X-RateLimit-Remaining and implement throttling to stay within 500/sec
- Concurrency issues: Monitor
X-Concurrent-Remaining and stay within your plan’s concurrent request limit
- Need higher limits: Contact support to discuss limit increases
Troubleshooting checklist
- Check headers: Monitor
X-Credits-Remaining, X-Concurrent-Remaining, and X-RateLimit-Remaining
- Verify requests: Ensure you’re only requesting needed features
- Implement retries: Use exponential backoff for 429 errors
- Monitor usage: Track credit consumption, concurrency patterns, and rate limit usage
- Optimize queries: Make prompts efficient and specific
