Skip to Content
Developers

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

AnswerRetry
429 provider_rate_limitedWait retry_after_ms, then retry.
503 provider_retryableExponential backoff: 1 s, 2 s, 4 s… up to about 1 minute.
401Get a new token, retry once.
Network error or timeoutBackoff, as for 503. See the warning below.
Any other 4xxDo 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.

On this page