Rate limits & quotas
Three independent layers protect your numbers and the platform. Every limit answers 429 with a
Retry-After header and a specific code.
1. Per key, per endpoint
| Endpoint group | Requests per minute per key |
|---|---|
/v1/messages |
60 |
/v1/sessions/... (incl. contacts, groups and message actions) |
120 |
/v1/webhooks/... |
30 |
These responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds).
Over the limit, you get 429 RATE_LIMITED.
2. Your plan
| Trial (24 hours) | Basic | Advanced | |
|---|---|---|---|
| WhatsApp sessions | the plan's | 1 | 3 |
| Messages per day | 100 per account | 500 per session | 500 per session |
| Messages per 30 days | – | 10,000 | 40,000 |
| Media per day | 20 per account | 50 per session | 100 per session |
| Webhooks | 1 | 3 | 10 |
| API keys (tenant-wide) | 1 | 2 | 10 |
| API requests per minute (account) | 30 | 60 | 180 |
| Multi-number pooling | – | – | ✓ |
| Code | HTTP | When |
|---|---|---|
DAILY_LIMIT_REACHED, MEDIA_LIMIT_REACHED |
429 | A daily quota is reached. It resets at 00:00 UTC |
PERIOD_LIMIT_REACHED |
429 | The 30-day quota is reached. It is a rolling window |
API_RATE_LIMITED |
429 | Requests per minute for the whole account |
PLAN_LIMIT_* |
402 | A count, such as sessions, is at the plan's limit. Upgrade to add more |
GET /v1/usage shows today's and recent days' messages, media and API requests, next to your limits.
Paying and billing calls are never rate-limited by your plan.
3. Per WhatsApp number
The safety engine's pacing and warm-up apply on top: see Safety & warm-up. These limits come from WhatsApp's behaviour, not from your plan, so a higher plan doesn't make one number send faster.
Handling 429
- Wait
Retry-Afterseconds before retrying. - Use exponential backoff for repeated 429s.
- For volume, use
?async=true. YASend queues the messages and sends each one as soon as the limits allow; setexpiresInSecondsfor anything time-sensitive.