Errors & limits

Status codes

Status	Meaning	What to do
`200` / `201`	Success
`207`	Bulk send partly failed	Check each item in `results`
`400`	Bad request	Fix the request body or parameters
`401`	Not authenticated, or missing a grant	Refresh your token, or check `required_grant`
`403`	Refresh token invalid, or origin not allowed (embed)	Log in again, or check your allowed sites
`404`	Not found	Check the ID or name
`422`	Validation failed (embed)	Read `message`
`429`	Rate limit exceeded	Wait a minute and retry, ideally with backoff
`500`	Server or WhatsApp error	Read `message`, which often contains WhatsApp’s reason

Error bodies

Most errors include a human-readable message:

{ "message": "Unauthorized to make this request", "required_grant": "/templates" }

The authentication and rate-limit endpoints use error instead:

{ "error": "Invalid credentials" }

To be safe, read message ?? error.

Common errors

Message	Cause
`Authorization token not provided`	The `Authorization` header is missing
`jwt malformed`	You sent `Bearer <token>`. Send the token on its own
`jwt expired`	The access token is older than 1 hour. Refresh it
`No Template found`	The template name doesn’t exist, or the template isn’t approved
Session message failed / re-engagement	The 24-hour window has closed. Send a template
`Rate limit exceeded. Please wait a minute and try again.`	More than 105 requests in a minute

Pagination

The /v2 endpoints and MCP tools are paginated:

Parameter	Description
`page`	Starts at 1
`pageSize`	Default and maximum depend on the endpoint (see the table below)

Responses echo back page and pageSize, and most include a total:

{ "data": { "contacts": [ … ], "page": 2, "pageSize": 20, "total": 134 } }

Endpoint	Default	Max
`/v2/contacts`	20	100
`/v2/conversations/recent`	20	50
`/v2/conversations/{id}/messages`	30	100
`/v2/templates`	50	100

Rate limits

Scope	Limit
REST API	105 requests per minute
MCP	60 requests per minute per Client ID
Embed session exchange	30 per minute per IP

WhatsApp also limits how many customers you can message each day, based on your number’s messaging tier. You can see your tier in the inbox header, e.g. “1K chats today · Tier 2K”. Keep the quality rating high to move up a tier.