Errors and Limits
Errors
Errors use HTTP status codes and a JSON body with a stable code and a readable message:
{ "error": { "code": "validation_error", "message": "Text is required (or one of image, video, audio, document, location, contact)." } }
Branch on code; the message may change.
| Status | code |
Meaning |
|---|---|---|
| 400 | invalid_json |
The body is not valid JSON. |
| 400 | validation_error |
A field is missing or wrong; the message says which. |
| 400 | no_webhook |
A webhook test without a webhook URL. |
| 401 | unauthorized |
No credential, or it is invalid or revoked. |
| 402 | workspace_suspended |
The workspace's plan has ended; sending and connecting are paused until it is renewed. |
| 403 | not_allowed |
The workspace has reached its session limit, or is suspended. |
| 403 | csrf_check_failed |
A POST, PUT, PATCH or DELETE without an Authorization header. |
| 404 | not_found |
No such session or message in your workspace. |
| 409 | already_linked |
Asking for a pairing code for a session that is already linked. |
| 429 | rate_limited |
Too many requests this minute. |
| 500 | internal_error |
Something went wrong on our side. Retry, and contact us if it continues. |
| 502 | whatsapp_error |
WhatsApp refused the request, or the session is not connected. |
| 502 | pairing_failed |
WhatsApp did not give a pairing code. |
| 504 | runtime_timeout |
WhatsApp did not answer in time. Retry in a moment. |
Rate limit
Messages, contacts and groups allow 600 requests a minute: per API key, or per workspace for requests with a personal access token. The count resets at the start of each minute. Over the limit you get 429 rate_limited; wait for the next minute and retry.
The rate limit protects the API. WhatsApp's own pace is slower: with account_protection on, each session sends one message every few seconds, and a long queue drains at that pace whatever the rate limit.
Other limits
| Limit | |
|---|---|
| Request body | 1 MB |
| Text message | 65,536 bytes |
| Images | 16 MB |
| Video, audio, documents | 64 MB |
| Mentions per message | 1,024 |
| Numbers per contact check | 50 |
| Message ids per read receipt | 100 |
| Messages per list page | 100 |
| Webhook answer | 10 seconds |
| Logs kept | 30 days |
Retrying safely
A POST /v1/messages that timed out on your side may still have been queued. Before you send it again, list recent messages with GET /v1/messages?limit=10 and check whether it is there.