WhatsApp API errors: 401, 403, 404, 422 and Meta errors

Last updated: 27 September 2026 · 7 min read

{ "error": "Invalid phone number: 123" }

Steps

1. 1

   401 and 403

   • 401 Invalid API key: the Authorization header is missing or the key is wrong. Take the key from the dashboard again (Profile settings › API access).
   • 403 You are not authorized to send from this inbox: the key's owner is not a member of that inbox. Use an administrator's key or add the agent to the inbox. Bulk sending also works only with an administrator's key.
2. 2

   404

   • No inbox with id X in this account: the channel_id is wrong or belongs to another account.
   • No message with id X: the message id is wrong or belongs to another account.
   • A bulk send's result returns 404 after 7 days.
3. 3

   422: the request itself

   • channel_id is required: there is no channel_id in the body.
   • Either text or template is required: neither text nor a template was sent.
   • conversation_status must be one of: ...: it can only be resolved, open or pending.
   • recipients must be a non-empty array: the recipient list of a bulk send is empty.
   • A batch can hold at most 1000 recipients: split the list into parts of 1000.
4. 4

   422: channel, window, template, number

   • The 24-hour messaging window ... is closed: the window is closed; add a fallback_template or send a template.
   • Inbox X is not a WhatsApp inbox: the given inbox is not WhatsApp.
   • This API requires a WhatsApp Cloud API inbox: the inbox is linked by QR; templates exist only on the Cloud API.
   • No approved template named '...': the template name or language code is wrong, or the template has not been synced to Clomni.
   • Invalid phone number: ...: the number does not have 8 to 15 digits, or the country code is missing.
5. 5

   Template “not found”

   There are two causes: the template is not APPROVED yet, or it has not been synced to Clomni. In the dashboard, click Sync Templates on the WhatsApp inbox's Configuration tab and check with GET /v1/accounts/{account_id}/whatsapp/templates.

   Take the language code exactly from the language field there: az and az_AZ are different templates.

6. 6

   Messages Meta rejects

   If a request passes Clomni and Meta rejects it, the message gets the failed status and the reason is written in the external_error field. The most common ones:

   • the number is not on WhatsApp: clean up your database, such numbers lower your quality rating;
   • a template parameter does not match: compare with example_parameters, the number of variables must be exact;
   • the template is paused (PAUSED): Meta paused it because of complaints, check in Business Manager;
   • the daily limit is reached: Meta's messaging limit (tier) is used up, continue the next day or raise the limit.
7. 7

   When you ask for help

   To find the problem quickly, have these ready:

   • account_id and channel_id
   • the body of the request you sent (without the API key)
   • the response you got and the HTTP code
   • the message id or batch_id
   • the approximate time of the request (hour and minute, with the time zone)

   Never send your API key to anyone.