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

# Rate Limits and Request Throttling

> CA Colombia API enforces per-window rate limits on endpoints. Learn the default limits, how to read rate limit errors, and which roles bypass throttling.

The CA Colombia API enforces rate limits using fixed-window counters to protect service availability. Each endpoint tracks requests per IP address within a defined time window, and if you exceed the allowed number of requests that window resets before you can continue. Limits vary by endpoint — public and user-facing endpoints use a higher default, while staff-only endpoints apply a stricter cap.

***

## Default Limits

Most endpoints apply the following default rate limit:

| Window     | Maximum requests |
| ---------- | ---------------- |
| 10 seconds | 50 requests      |

Staff-only endpoints (such as character approval and review workflows) apply a stricter limit:

| Window   | Maximum requests |
| -------- | ---------------- |
| 1 minute | 10 requests      |

<Note>
  Rate limits are applied **per IP address**. All requests originating from the same IP — regardless of which user account is authenticated — share the same quota for a given endpoint.
</Note>

***

## Rate Limit Exceeded Response

When you exceed the allowed number of requests within a window, the API returns an HTTP `429` response with the following body:

```json theme={null}
{
  "error": "You are being rate limited!"
}
```

You should pause new requests until the current window has reset before retrying. The response does not currently include `Retry-After` headers, so you should implement your own backoff strategy (see [Best Practices](#best-practices) below).

***

## Roles That Bypass Rate Limits

Accounts with any of the following roles are exempt from rate limiting and will never receive a `429` response:

| Role                    | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `SERVICE_ADMINISTRATOR` | Full administrative access to the platform.                  |
| `DEVELOPER`             | Internal developer access with elevated privileges.          |
| `BOT`                   | Automated integration accounts with unrestricted throughput. |

<Note>
  If your application requires sustained high-volume access, contact the CA Colombia team about obtaining a `BOT` role for your integration account.
</Note>

***

## Best Practices

<Tip>
  Implement **exponential backoff** when you receive a `429` response. Start with a short pause (for example, 1 second), then double the wait time on each successive retry up to a reasonable maximum (for example, 30 seconds). This prevents your client from hammering the API immediately after a window resets and triggering another rate limit.
</Tip>

* **Cache responses** that are unlikely to change frequently (such as user profile data) to reduce the number of requests you make within each window.
* **Monitor `429` responses** in your logging and alerting pipelines so you can identify when a part of your integration is approaching its limit before users are impacted.