Skip to main content

The short answer

Your agent receives a 429 Too Many Requests response. The response includes a Retry-After header that tells you exactly how many seconds to wait before retrying. Implement exponential backoff — retry after the indicated delay, and double the wait on each subsequent failure. Do not retry immediately. Hammering the API after a 429 makes the situation worse and can trigger longer cooldowns.

Rate limits by plan

Per-minute limits reset on a rolling window. Per-day limits reset at midnight UTC.

What a 429 response looks like

retryAfter is in seconds. Read it from the JSON body or the Retry-After header — both are present.

How to handle 429 in code

Key points:
  • Start with the retryAfter value from the response, not an arbitrary constant
  • Multiply by 2^attempt on each retry — exponential, not linear
  • Cap the maximum wait to something reasonable (e.g. 10 minutes) for long-running queues
  • Log every 429 — a spike in rate limit errors signals a sending strategy problem, not just a transient issue

Protecting your deliverability

Rate limits exist for two reasons: protecting the API and protecting your sender reputation. The second one matters more. Blasting thousands of emails in a short window triggers spam filters at the receiving end — regardless of what your plan allows. Gmail, Outlook, and corporate mail servers track sending velocity per IP and domain. A sudden spike looks like a compromised account or a spam campaign. The plan limit is a ceiling, not a target. Stay well below it, especially on new domains. Warmup ramp matters more than plan limit. A new domain sending 1,000 emails on day one will land in spam even if the Business plan technically allows it. The domain needs a reputation first. See How to warm up a domain for the full ramp schedule.

Batching large sends

If your agent needs to send a large volume — campaign emails, digest notifications, bulk outreach — spread the sends over hours or days rather than issuing them all at once.
For very large lists (10,000+), push sends into a job queue (e.g. BullMQ, Celery) with concurrency limits rather than running them in a single process loop. This gives you retry durability, observability, and natural rate control.

Rate Limits

Full reference for all per-plan rate limit tiers and how limits are enforced.

Sending Messages

Complete API reference for commune.messages.send() and message delivery options.

How to Warm Up a Domain

Ramp schedule and warmup strategy for new sending domains.
Last modified on March 19, 2026