Skip to content

Rate limits

Limits protect shared infrastructure and apply per token, not per workspace.

  • Each token may make 30 requests in any 10-second window. Beyond that the API answers 429 with a Retry-After header (seconds).
  • Lists return at most 100 items per page.
  • Paging is offset based and capped: page_number x page_size must not exceed 10,000. A request beyond that answers 400 with the message "page_number x page_size must not exceed 10000. Narrow the list with filters instead of paging that deep." Cursors do not exist yet, so to read more than 10,000 records narrow the query with the endpoint's filters (for example tag or search on contacts, or status on conversations, templates and broadcast recipients; the Endpoints page lists each one) and read each slice separately. When a list reaches the cap the response sets window_exhausted to true and has_more to false even though more records exist.
  • One template send call accepts at most 100 recipients. Send several calls for larger audiences, or use a broadcast in the app.
  • A local_message_id is remembered for 24 hours per recipient, so a retry after a timeout never sends twice. Reusing the same local_message_id with a different body answers 422 and sends nothing; use a new local_message_id for a different message. If an earlier call with the id is still being recorded the API answers 409; wait a few seconds and retry with the same id. A call that never finished is treated as abandoned after about a minute, and the next retry sends normally.
  • WhatsApp's own limits (24-hour window, your number's messaging tier, template approval) are enforced separately and can refuse a send even when the API accepts the call.

When you receive 429, wait for Retry-After, then retry with the same local_message_id values.