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

> 600 requests per minute per API key (bursts up to 600, refilling 10 per second), with X-RateLimit-* response headers and 429 backoff guidance.

Each API key has a rate limit of **600 requests per minute**: bursts of up to 600 at once, refilling at 10 per second. The limit is the same whatever scopes the key holds. Keys with a custom limit keep that instead, and the `X-RateLimit-Limit` header on every response tells you your key's exact limit.

## How the limit works

* **It counts requests, nothing else.** A call that lists a 10-contact audience and a call that imports a million contacts each cost one request. Payload size, list size, and message volume never count.
* **Bursts are fine.** Think of a bucket holding 600 tokens; each request spends one, and tokens refill at 10 per second. You can send 600 at once, and after that you keep getting 10 per second rather than being locked out for the rest of the minute. A steady 10 per second never hits the limit.
* **It is per key.** Each key has its own budget. If two systems share one key they share one budget; give each integration its own key.
* **You can see it.** Admin > API > your key > usage shows total requests, success rate, and how many requests were rate limited.

```http theme={null}
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1640995260
```

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Maximum requests allowed in the current window. |
| `X-RateLimit-Remaining` | Requests you can send right now (tokens left in the bucket). |
| `X-RateLimit-Reset` | Unix timestamp (seconds). On a normal response, when your full allowance is available again. On a `429`, when your next request will be allowed. |

## What happens at the limit

When you hit the limit, subsequent requests return `429 Too Many Requests` with a `Retry-After` header: the seconds until your next request will be allowed. At the default limit that is about one second. If both `Retry-After` and `X-RateLimit-Reset` are present, `Retry-After` wins (it is relative, so a skewed clock cannot mislead you). The official SDKs already do this.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 1
```

```json theme={null}
{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Maximum 600 requests per 60 seconds",
  "code": "RATE_LIMIT_EXCEEDED",
  "statusCode": 429,
  "retryAfter": 1
}
```

## 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 for the `Retry-After` seconds (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>

  <Accordion title="Poll project stats no faster than they change">
    `GET /v1/projects/{id}/stats` is cached for 15 seconds while a project is sending and 5 minutes once it is idle, so polling faster than that returns the same numbers for another request. For many projects at once, `GET /v1/projects/stats` with a date range returns them in one call.
  </Accordion>
</AccordionGroup>

## Need a higher limit?

If your integration's design genuinely requires more than 600 requests/minute 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.