> For the complete documentation index, see [llms.txt](https://api-reference.usecommune.dev/llms.txt)

# Rate limits

Every request is counted against the credential that made it, never against
an address. Three budgets apply:

* `general` counts every request.
* `audience`, which is tighter, counts only the operations that return
  subscriber or recipient email addresses.
* `write`, equally tight, counts only the operations that change something.

An operation covered by one of the narrow budgets is charged to it and to
`general`, and has to pass both.

From the moment a credential resolves, every response carries
`RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` for whichever
budget is closest to exhaustion, and `RateLimit-Policy` listing every budget
that applied. `RateLimit-Reset` is in seconds from now. A `429` additionally
carries `Retry-After`, and its `message` names the budget that refused:
being refused by the `audience` budget still leaves the rest of the API
callable.

`GET /rate-limit` reports every budget at once, which is what to read rather
than inferring the whole picture from the one budget the headers describe.

## Example
An `audience` read, with the `audience` budget closest to running
out, so it is the one the triple describes:

```http
HTTP/1.1 200 OK
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 41
RateLimit-Policy: "general";q=600;w=60, "audience";q=60;w=60
```

The same budget, spent:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 12
RateLimit-Policy: "general";q=600;w=60, "audience";q=60;w=60
```

```json
{
  "error": {
    "code": "rate_limited",
    "message": "This key has spent its \"audience\" rate limit budget of 60 requests per 60 seconds. Reads that return subscriber or recipient email addresses, counted separately from and more tightly than everything else. Retry in 12 seconds; RateLimit-Policy on this response lists every budget that applies.",
    "docs_url": "https://usecommune.dev/errors/rate_limited",
    "request_id": "req_6f1c0e9b2d8a4f7c9e3b5a1d0c8f2e4b"
  }
}
```

Every budget at once:

```shell
curl https://api.usecommune.com/rate-limit \
  -H "Authorization: Bearer $COMMUNE_API_KEY" \
  -H "Commune-Version: 2026-08-26"
```

