Skip to main content
The cloro API uses a credit-based billing system with concurrency limits to ensure fair usage and service reliability.

​
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
  • See Request & Response for endpoint pricing details

​
Response headers

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)

​
Rate limit information (all endpoints)

HeaderDescription
X-RateLimit-LimitMaximum requests per second allowed (500)
X-RateLimit-RemainingRemaining requests available in this second

​
Credit information (monitor endpoints)

HeaderDescription
X-Credits-RemainingNumber of credits remaining in your account
X-Credits-ChargedNumber of credits charged for this request

​
Concurrency information (monitor endpoints)

HeaderDescription
X-Concurrent-LimitMaximum number of concurrent requests allowed
X-Concurrent-CurrentCurrent number of concurrent requests
X-Concurrent-RemainingNumber 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 help ensure service stability 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"
  }
}
Implement retry logic with exponential backoff: 
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

  1. Check headers: Monitor X-Credits-Remaining, X-Concurrent-Remaining, and X-RateLimit-Remaining
  2. Verify requests: Ensure you’re only requesting needed features
  3. Implement retries: Use exponential backoff for 429 errors
  4. Monitor usage: Track credit consumption, concurrency patterns, and rate limit usage
  5. Optimize queries: Make prompts efficient and specific