Guide

Rate limits and quotas

Requests per API key

Each API key may make a number of requests per minute across all /v1 endpoints: 300 by default, changeable per key in API keys up to what your plan allows. The window slides over the last minute and only counts that key (dashboard logins are not limited). Every response tells you where you stand:

RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41

RateLimit-Reset is the number of seconds until the window rolls over.

Sending and other heavy calls

Some calls also have their own one-minute limit per key:

Handling 429

Over a limit you get 429 with code: RATE_LIMITED and a Retry-After header (seconds). Refused requests are not counted, so waiting that long is enough:

async function call(url, init, tries = 5) {
  for (let i = 0; ; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429 || i === tries - 1) return res;
    const wait = Number(res.headers.get('Retry-After') ?? 1) * 1000;
    await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
  }
}

Monthly quotas

Plans include a number of messages per month and of devices. GET /v1/usage shows this month's use. When a plan without overage reaches its message quota, further messages end as failed with the error quota_exceeded; plans with overage keep sending and bill the extra messages. AI replies have their own monthly quota (GET /v1/ai-reply).

Delivery pace is separate

Limits apply to API calls. How fast WhatsApp receives messages is set by each device's queue, whatever the plan — see Pacing.