Commune

429rate_limited

Rate limited

A rate limit budget or a daily send limit is spent. Wait `Retry-After` seconds; the message names which limit it was.

Each credential has several budgets, counted separately, and a request is charged to every budget it belongs to. Every response (not just this one) reports them: RateLimit-Policy lists each budget, and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset describe the one closest to running out. GET /rate-limit returns the same numbers as JSON. The budgets are per credential (per API key, or per OAuth authorisation), not per IP address, and the numbers below are the defaults.

The message names the budget that ran out. That matters, because they are not interchangeable: running out of the audience budget does not stop you making other calls, and running out of the general one does.

Sending has a second kind of limit, a daily cap that is not one of the RateLimit-Policy budgets and does not reset with them. When one of those answers, the message says so and Retry-After is measured in hours rather than seconds.

Why it happens, and how to fix it

  1. The general budget is spent

    Every request made with the credential counts against general, by default 600 requests per 60 seconds. Tight polling loops, parallel pagination and retry storms are the usual reasons.

    Fix: Wait Retry-After seconds, then continue. Watch RateLimit-Remaining and slow down before it reaches zero. Prefer webhooks to polling for changes.

  2. The audience budget is spent

    Reads that return subscriber or recipient email addresses (GET /newsletters/{newsletter}/subscribers, GET /subscribers/{subscriber}, GET /newsletters/{newsletter}/insights and GET /newsletters/{newsletter}/events) also count against audience, by default 60 per 60 seconds.

    Fix: Page with limit=100 rather than many small pages, cache what you have read, and keep doing other work while you wait: the other budgets are unaffected.

  3. The write budget is spent

    Requests that change something also count against write, by default 60 per 60 seconds, because each one can publish an event to someone's endpoint.

    Fix: Batch where the API allows it (for example POST /tags/{tag}/subscribers tags up to 500 subscribers in one request) and pace the rest under the limit.

  4. The daily limit on sends to a list

    POST /articles/{article}/send and POST /articles/{article}/schedule are limited, by default, to 25 dispatches per newsletter per day, counted across every credential. It counts dispatches, never recipients, so the size of the list does not matter. A schedule counts as a send, and a refused send counts for nothing.

    Fix: Wait the Retry-After the response gives (hours, not seconds). If an integration is hitting this, it is probably sending the same article repeatedly; check your retry logic and use the same Idempotency-Key for retries.

  5. The daily limit on test sends

    POST /articles/{article}/test-send is limited, by default, to 50 per credential per day. Each test send request counts once, whether it goes to one address or five, and one that was refused counts for nothing. It is the only operation that mails people who never subscribed, so it is counted apart.

    Fix: Wait Retry-After (hours, not seconds). Put every address you want a copy at into one request's to (up to 5) rather than sending one request per address.

Retrying

Yes: send the same request again after Retry-After seconds (with the same Idempotency-Key for a write), and not before.

Headers

  • Retry-After

    Whole seconds to wait before retrying. Always at least 1.

  • RateLimit-Policy

    Every budget that applies to the request, as "name";q=<limit>;w=<window seconds>, comma separated. Daily send limits are not listed here.

  • RateLimit-Limit

    The size of the budget closest to running out.

  • RateLimit-Remaining

    Requests left in that budget.

  • RateLimit-Reset

    Seconds until that budget refills.

Example response

HTTP 429
{
  "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 23 seconds; RateLimit-Policy on this response lists every budget that applies.",
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/rate_limited"
  }
}

Often confused with conflict, service_unavailable.