> ## Documentation Index
> Fetch the complete documentation index at: https://cloro.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits & limits

> Understanding API credits, pricing, rate limits, concurrency, and usage monitoring for all cloro monitoring endpoints and request management.

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](/guides/providers#sync-request-surcharge) for details)
* See [Request & Response](/guides/making-requests) for endpoint pricing details
* For [batch requests](/api-reference/endpoint/create-batch-tasks), credits are tracked per task within the batch. Each task's result includes its own `creditsToCharge` and `creditsCharged` values

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

| Header                  | Description                                 |
| ----------------------- | ------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per second allowed (1,000) |
| `X-RateLimit-Remaining` | Remaining requests available in this second |

### Credit information (monitor endpoints)

| Header                | Description                                 |
| --------------------- | ------------------------------------------- |
| `X-Credits-Remaining` | Number of credits remaining in your account |
| `X-Credits-Charged`   | Number of credits charged for this request  |

### Concurrency information (monitor endpoints)

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

```json theme={null}
{
  "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:

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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)

```javascript theme={null}
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 1,000/sec per endpoint
* **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