Rate limits and retries
How sending is limited, and how to retry safely.
Sending is limited per number: WhatsApp allows each number a limited rate of messages, and the API enforces it before calling WhatsApp. Over the limit, a send answers 429 with provider_rate_limited and retry_after_ms.
When to retry
| Answer | Retry |
|---|---|
429 provider_rate_limited | Wait retry_after_ms, then retry. |
503 provider_retryable | Exponential backoff: 1 s, 2 s, 4 s… up to about 1 minute. |
401 | Get a new token, retry once. |
| Network error or timeout | Backoff, as for 503. See the warning below. |
Any other 4xx | Do not retry: fix the request. |
Retries can duplicate a message
If a send times out, you cannot tell whether WhatsApp received it. A retry can then deliver the message twice. Set client_ref on each send: the same reference on two messages tells you one of them is a duplicate.
Sending a lot
- Use
send/batch: up to 1000 messages per call, each with its own result. - Retry only the failed items of a batch, using the rules above.