Errors & rate limits
Every error the Wazline API can return, what it means, and how to handle it.
Error format
Errors return a non-2xx status code and a JSON body:
{
"success": false,
"error_code": "template_not_found",
"message": "No approved template with that name was found."
}Use error_code in your code — it doesn’t change. message is a human-readable explanation and may be reworded.
Error codes
| Status | error_code | Meaning |
|---|---|---|
| 401 | invalid_token | The Authorization header is missing, or the token is wrong, was regenerated, or belongs to a disabled or deleted client. |
| 403 | host_not_allowed | The Origin or Referer header is missing, or doesn’t match the client’s Allowed Host. |
| 403 | number_mismatch | The request named a different WhatsApp number from the token’s. Leave whatsapp_number_id out — the token already identifies the number. |
| 404 | template_not_found | No approved, synced template with that name exists for the token’s number. |
| 422 | invalid_payload | A required field is missing or has the wrong type. |
| 422 | params_mismatch | There are fewer template values than variables, or a value is empty. |
| 422 | invalid_number | The phone number couldn’t be read. Include the country code. |
| 422 | window_closed | Text messages only: the customer hasn’t written in the last 24 hours. |
| 422 | number_not_found | Text messages only: no WhatsApp number is linked to the token. |
| 429 | — | Too many requests — see below. |
| 502 | send_failed | WhatsApp rejected the send. |
Rate limits
Each endpoint accepts 60 requests per minute from the same IP address. Above that you’ll get 429 Too Many Requests. Wait the number of seconds in the Retry-After header, then try again.
For large volumes, queue messages on your side and send them at a steady pace. To message a whole list at once, use a campaign instead.
Handling errors
- 401 and 403 — a configuration problem. Don’t retry; fix the token, the host or the number.
- 404 and 422 — a problem with the request. Correct the data before retrying.
- 429 — wait for
Retry-After, then retry. - 502 — WhatsApp refused the message. Retry once after a short delay; if it keeps failing, check the template and the recipient’s number.
Phone number format
The to field accepts international numbers in the usual formats: +971501234567, 971501234567, 00971501234567, and with spaces or dashes. A number that starts with a single 0 (local format) is rejected — always include the country code.
Our team is happy to walk you through Wazline and help you set up your workspace.