Rate limits and quotas
The API applies rate limits so that no single integration can overwhelm shared infrastructure. When you exceed a limit, requests are throttled rather than failed permanently — your job as a developer is to detect throttling and back off gracefully. This page summarizes the limit types you may encounter and how to respond to them. Exact ceilings depend on your plan and account configuration (confirm the values that apply to your account).
Reference
| Item | Typical value / behavior | Notes |
|---|---|---|
| Requests per second (per API key) | e.g. 10 req/s (burst allowance may be higher) | Steady-state limit; short bursts above the rate are usually tolerated. |
| Throttled response status | 429 Too Many Requests | Signals you should slow down and retry later. |
Retry-After header | Seconds to wait before retrying, e.g. 2 | When present, honor it exactly instead of retrying immediately. |
| Rate-limit headers | e.g. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | Use these to pace requests before you hit the limit. Header names are placeholders — verify them in your account. |
| Daily send / transactional quota | Per-plan ceiling on messages sent | Separate from request rate; sending stops or queues once reached. |
| Bulk import batch size | e.g. 1,000 records per request | Split large audience imports into batches rather than one large call. |
| Concurrent connections | Small fixed number per key | Parallelize modestly; excessive concurrency counts toward throttling. |
Notes
- Back off exponentially. On a
429, wait, then retry with increasing delays (e.g. 1s, 2s, 4s) plus a little random jitter to avoid synchronized retries. Always prefer theRetry-Aftervalue when it is supplied. - Make requests idempotent. Design retries so a repeated call cannot double-send a Broadcast or create duplicate subscribers.
- Pace proactively. Read the remaining/reset headers and slow down before you are throttled, rather than reacting only to errors.
- Rate limits and quotas are different. A rate limit governs how fast you call the API; a quota governs total volume (for example, sends per day). Hitting a quota is not solved by retrying.
- Cache and batch. Reuse tokens, cache reference data, and batch writes to stay well under your ceilings.
Related
Canonical terms: Author, Edition, Folder (Project Folder), Broadcast. See the Glossary.