Every request is counted against the credential that made it, never against an address. Three budgets apply:
generalcounts 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.
An audience read, with the audience budget closest to running
out, so it is the one the triple describes:
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/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
{
"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:
curl https://api.usecommune.com/rate-limit \
-H "Authorization: Bearer $COMMUNE_API_KEY" \
-H "Commune-Version: 2026-08-26"