Rate limits

Sooner applies two separate limits. The request rate limit controls how fast you can call the API. The email quota controls how many emails you can send in a month.

Request rate limit

The limit is per team, not per key or per project. All keys and projects in a team share one budget. It is a token bucket: the sustained rate is the number of requests per second for your plan, and the bucket holds twice that, so short bursts are allowed.

Every authenticated request uses one token, including requests that later fail validation. Requests with a missing or invalid key do not.

When the bucket is empty, the API returns 429 with the error name rate_limit_exceeded and a retry-after header in seconds:

HTTP/1.1 429 Too Many Requests
retry-after: 1
content-type: application/json

{
  "statusCode": 429,
  "message": "Too many requests. Your plan allows 10 requests/second.",
  "name": "rate_limit_exceeded"
}

To send many emails with fewer requests, use POST /emails/batch, which sends up to 100 emails in one request and uses one token.

Monthly email quota

Each plan includes a number of emails per calendar month, counted in UTC. The counter resets at 00:00 UTC on the first day of the month.

• Each email accepted by the API counts once, however many recipients it has in to, cc and bcc.
• A batch of N emails counts N.
• A scheduled email counts when you create it. If you cancel it, the count is returned.
• An email that is accepted but not sent because every recipient is suppressed still counts.
• Each broadcast recipient that is queued counts.

Free plan: hard caps

On Free, the quotas are hard limits.

• When the monthly quota is used up, sends return 429 with monthly_quota_exceeded. There is no retry-after header. Sending resumes on the first of the next month (UTC) or when you upgrade.
• The daily cap of 500 resets at 00:00 UTC. A send that would pass the cap returns 429 with daily_quota_exceeded and a retry-after header holding the seconds until it resets.
• A request that would cross a cap is rejected as a whole. A batch is never partly accepted.

Paid plans: overage

On Pro, Scale and Enterprise there is no daily cap and sending never stops at the monthly quota. Emails above the quota are billed per 1,000 on your next invoice. See Billing and plans.

Check your usage

GET /usage returns your usage against the monthly and daily limits. The Billing page in the dashboard shows the same month-to-date number.

Handling limits in code

Retry rate_limit_exceeded and daily_quota_exceeded after the retry-after delay, and do not retry monthly_quota_exceeded. Always send an Idempotency-Key so that a retry cannot duplicate an email. See Errors for a retry helper and Idempotency.