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

# Rate Limits

> Understand API rate limiting and how to handle it effectively

## Overview

APIs often enforce **rate limits** to prevent abuse and ensure stability. This section explains how rate limits work, the relevant headers, and how to handle cases when the limit is exceeded.

## Rate limit Headers

The API provides the following headers in each response to help you manage your request quota:

| Header                  | Description                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `x-ratelimit-limit`     | Total number of requests allowed in the current time window                                     |
| `x-ratelimit-remaining` | Number of requests remaining in the current time window                                         |
| `x-ratelimit-reset`     | Number of seconds until the rate limit resets                                                   |
| `retry-after`           | If the limit has been reached, how many seconds the client must wait before making new requests |

### Example Headers

```http theme={null}
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 120
retry-after: 0
```

## When the limit is reached

If you exceed the allowed number of requests, the API responds with **HTTP 429 Too Many Requests**.

### Example Response

**Headers**:

```http theme={null}
x-ratelimit-limit: 1000
x-ratelimit-remaining: 0
x-ratelimit-reset: 120
retry-after: 119
```

**Body**:

```json theme={null}
{
  "error": "Too Many Requests",
  "error_description": "Rate limit exceeded, retry in 119 seconds"
}
```

## Best practices for handling rate limits

* Always check `x-ratelimit-remaining` before making requests.
* Respect the `retry-after` header to avoid being blocked.
* Implement exponential backoff or request queuing.
* Cache responses when possible to reduce unnecessary requests.