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

# Rate limiting

> Per-endpoint limits, response headers, and backoff guidance.

## Overview

The API enforces rate limits to protect the service and ensure fair usage. Limits are applied **per API key** (the same key you send as `x-api-key`), not per IP address. Each quota uses a **sliding window** (e.g. “60 requests per 60 seconds”).

Plan-specific quotas may still apply elsewhere; when in doubt, treat limits as documented in your contract or dashboard.

## Limits by endpoint

All paths below are under the **`/v1`** prefix (for example, `GET /v1/campaigns`).

| Method | Path                        | Limit               |
| ------ | --------------------------- | ------------------- |
| `GET`  | `/analytics`                | 30 requests / 60 s  |
| `GET`  | `/analytics/daily`          | 30 requests / 60 s  |
| `GET`  | `/analytics/by-user`        | 30 requests / 60 s  |
| `POST` | `/leads/add_to_campaign`    | 20 requests / 60 s  |
| `GET`  | `/campaigns`                | 60 requests / 60 s  |
| `GET`  | `/campaigns/:id`            | 120 requests / 60 s |
| `GET`  | `/campaigns/:id/statistics` | 30 requests / 60 s  |
| `GET`  | `/users`                    | 60 requests / 60 s  |
| `GET`  | `/users/:id`                | 60 requests / 60 s  |
| `GET`  | `/teams/me`                 | 60 requests / 60 s  |

**Default for API-key routes:** Any authenticated route that uses the standard API key guards but does **not** declare its own limit falls back to **60 requests / 60 s** per API key.

## Response headers

When the rate limit check runs successfully, responses include:

* **`X-RateLimit-Limit`** — maximum requests allowed in the current window.
* **`X-RateLimit-Remaining`** — requests remaining in the current window.
* **`X-RateLimit-Reset`** — Unix timestamp in milliseconds when the limit window resets.

These headers are set on **successful** responses (HTTP 2xx) as well as on **429** responses, so clients can throttle before hitting the cap.

## When you hit the limit

You will receive **429 Too Many Requests**. The response includes:

* The same **`X-RateLimit-*`** headers as above.
* **`Retry-After`** — suggested wait time in **seconds** before retrying.

Stop hammering the API: honor **`Retry-After`** or wait until **`X-RateLimit-Reset`**, then retry with a small buffer.

## Backoff strategy

1. Prefer **`Retry-After`** on 429 responses, or sleep until **`X-RateLimit-Reset`** (with a small buffer).
2. If those headers are missing, use exponential backoff (e.g. 1s, 2s, 4s, …) with jitter, and cap the maximum delay.

## Operational note

If the rate-limit backend is temporarily unavailable, the API may **allow** the request without setting **`X-RateLimit-*`** headers. This is rare; normal operation always includes those headers when the check succeeds.