Rate limits
The API limits how fast you may make requests. It is separate from how many emails your plan lets you send.
What is limited
Requests, per workspace. The limit is derived from your plan, and it is not per key:
creating extra API keys does not raise it. Live and test traffic have separate allowances, so
a load test against a tix_test_ key cannot slow production down.
The bucket refills continuously rather than resetting on a boundary, so a short burst above the sustained rate is fine as long as you are under it on average.
The headers
Every response carries the current state, so you rarely need to guess.
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed in a full burst |
RateLimit-Remaining | Requests available right now |
RateLimit-Reset | Seconds until another request is allowed, 0 when one already is |
RateLimit-Policy | The limit and its window in seconds |
RateLimit-Scope | Always workspace |
Reading RateLimit-Remaining and slowing down before it reaches zero is better than waiting
to be rejected.
When you go over
rate_limit_exceeded, status 429, with a Retry-After
header in seconds. Nothing was sent and nothing was charged, so the request is safe to repeat
once the wait has elapsed.
HTTP/1.1 429 Too Many Requests
Retry-After: 2
RateLimit-Remaining: 0
Honour Retry-After rather than picking your own interval. Retrying sooner consumes capacity
you do not have and makes the queue behind you longer.
Rate limits are not quotas
They fail differently and are fixed differently.
| Rate limit | Send quota | |
|---|---|---|
| Counts | Requests per second | Emails per day and per month |
| Error | rate_limit_exceeded | daily_quota_exceeded, monthly_quota_exceeded |
| Clears | Within seconds | At the daily reset, or on a plan change |
| Fix | Slow down | Send less, or upgrade |
A daily quota failure also carries Retry-After, set to the seconds remaining until the next
UTC midnight. A monthly one does not, because waiting will not help.
Reducing how many requests you need
Use POST /v1/emails/batch to submit up to 100 messages in one request. A hundred
individual sends and one batch of a hundred cost very different amounts of your request
allowance and deliver the same mail.