1MSG WhatsApp API errors and how to fix them
Errors the 1MSG API returns when a message can't be sent, with the cause and the fix. Note that many send errors come back as HTTP 200 with "sent": false, so always check the sent field, not only the HTTP status.
| Status | API response | Cause | Fix |
|---|---|---|---|
| 200 | Message was not sent: template is not defined | namespace, template or language is missing from the request body. | Send all three. Take namespace and the exact template name from GET /templates; language is an object: {"policy": "deterministic", "code": "en"}. |
| 200 | template name (…) does not exist in <language> | The template is approved in a different language than the one requested. | Use the exact language code the template was approved in (for example es_MX is not the same as es). Check it in GET /templates. |
| 200 | Message was not sent: provide chatId, phone, bsuid, or username | No recipient the channel could resolve. | Pass exactly one recipient: phone (country code plus number, digits only), chatId (for example [email protected]) or bsuid. |
| 200 | Message was not sent: empty body | The body field is missing or empty. | Send a non-empty body string. It is required for text, reply-button and list messages. |
| 200 | wrong file | The media could not be fetched or uploaded: the URL is not reachable or the base64 is invalid. | Pass a public HTTPS URL or valid base64 in body, or upload the file with /uploadMedia and send mediaId with mediaType. |
| 200 | Message was not sent: filename | sendFile was called without filename, so the file has no extension. | Add filename with an extension, for example invoice.pdf. |
| 401 | token is required | The request has no token. | Add your channel token as the token query parameter: https://api.1msg.io/{channelId}/{method}?token=… |
| 429 | too many requests. please try later | The channel is over its send rate. | Queue messages on your side and retry with exponential backoff. |
| 403 | access denied | The token is wrong, or belongs to a different channel than the URL. | Check that the token and the channelId in the URL belong to the same channel. |
Full API reference: https://docs.1msg.io/