Rate Limits
How sending gateways and the AI Gateway are throttled, and how to handle it.
Different parts of the Mersal API are rate-limited differently, depending on whether you're sending messages through a channel gateway or calling the AI Gateway.
Channel gateways (SMS, WhatsApp, Email)
Each sending gateway on your account has configurable rate-limit presets — per-minute, per-hour, and per-day caps — that genuinely limit how fast messages go out. These limits exist to protect deliverability (providers penalize accounts that burst-send too aggressively) and to match the throughput your connected provider actually supports.
Rate-limit presets are configured per gateway in your account's Gateways settings. If you're sending a large batch, prefer a single request with many contact entries (bulk send) over many rapid individual requests — this lets Mersal schedule the fan-out against the gateway's configured limits internally, rather than you racing against them from the client side.
If you have predictable, large sends (e.g. a monthly newsletter to your full contact list), use schedule_at to spread delivery rather than firing everything at once — this plays better with gateway-level throughput limits.
AI Gateway
POST /api/ai/v1/chat/completions applies request throttling to protect shared AI capacity across all customers using the AI Pool. Limits are configured per AI Pool key, both per-minute and per-day. If you need higher throughput for a production workload, check your AI Pool key's configured limits in the dashboard.
Handling throttling
When you're rate-limited, back off rather than retrying immediately in a tight loop:
- Use exponential backoff — wait progressively longer between retries (e.g. 1s, 2s, 4s, 8s) rather than retrying at a fixed short interval.
- Add jitter (a small random delay) to avoid many clients retrying in lockstep after a shared limit resets.
- For bulk sends, prefer batching contacts into fewer requests over issuing one request per recipient.
Don't hardcode limit numbers
Exact rate-limit values are configurable per account and per gateway/key, and can change. Build your integration to read and respect throttling responses dynamically rather than hardcoding a specific number of requests per minute.
See also
- Errors and Status Codes — general error response conventions.
- Authentication — where channel and AI Pool keys are managed.