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

# Rate Limits

> 100 requests per hour per API key, with X-RateLimit-* response headers and 429 backoff guidance.

Each API key has a rate limit of **100 requests per hour**. Rate-limit state is returned on every response in the headers below.

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1640995200
```

| Header                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window. |
| `X-RateLimit-Remaining` | Requests remaining in the current window.       |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the limit resets. |

## What happens at the limit

When you hit the limit, subsequent requests return `429 Too Many Requests` with error code `RATE_LIMIT_EXCEEDED` until the reset timestamp passes.

```json theme={null}
{
  "success": false,
  "error": "Rate limit exceeded. Try again after the X-RateLimit-Reset timestamp.",
  "code": "RATE_LIMIT_EXCEEDED",
  "statusCode": 429
}
```

## Handling 429s correctly

<AccordionGroup>
  <Accordion title="Monitor X-RateLimit-Remaining on every response">
    Don't wait for a 429 - track the remaining counter and start backing off when it gets low (e.g. below 10).
  </Accordion>

  <Accordion title="Implement exponential backoff for 429 responses">
    Standard pattern: on 429, sleep until `X-RateLimit-Reset` (or for an initial delay of 1s, doubling each retry up to a cap). Retry the same request. Never retry tighter than once per second.
  </Accordion>

  <Accordion title="Use caching to reduce API calls">
    Cache hierarchy data for 5–10 minutes (it changes infrequently). Cache historical stats for completed date ranges indefinitely.
  </Accordion>

  <Accordion title="Batch operations when possible">
    Prefer one large date-range query over many small ones. Use hierarchy filters (`organization_id`, `brand_id`, `campaign_id`) to reduce data volume per request.
  </Accordion>
</AccordionGroup>

## Need a higher limit?

If your integration's design genuinely requires more than 100 requests/hour per key, contact [support@politicalcomms.com](mailto:support@politicalcomms.com) with details on your use case. We can issue keys with elevated limits for production integrations that demonstrate good caching and batching practices.