Errors

Errors use normal HTTP status codes. API errors have this body:

{
  "success": false,
  "error": { "code": "WINDOW_CLOSED", "message": "The 24-hour window with this contact is closed — send an approved template instead" }
}

Branch on error.code (stable); show or log error.message (may be reworded).

Status	Code	Meaning	What to do
400	INVALID_NUMBER	to is not a valid WhatsApp number	Use international format, e.g. +919812345678
400	BAD_PHONE	phone is not valid (contacts)	Same as above
400	MISSING_TEXT / TEXT_TOO_LONG	No text, or over 4,096 characters	Fix the text
400	MISSING_TEMPLATE	template.name missing	Add the template name
400	MISSING_MEDIA / BAD_MEDIA_LINK	No media link/id, or the link isn’t https	Use a public https URL
400	BAD_INTERACTIVE	Buttons or list break WhatsApp’s limits	Read the message — it names the limit
400	BAD_TYPE	Unknown type	Use one of the documented types
400	BAD_FIELDS	fields is not an object	Send { "name": "value" }
400	NO_CHANNEL	No active connected number, or the channel_id isn’t yours or isn’t active	Connect a number / fix channel_id
401	NO_API_KEY / INVALID_API_KEY	Missing or wrong key	See Authentication
402	SUBSCRIPTION_EXPIRED	Plan expired	Renew in the panel
403	ACCOUNT_SUSPENDED	Account suspended	Contact support
403	CHANNEL_NOT_ALLOWED	The key is limited to another number	Use the right key or drop channel_id
403	OPTED_OUT	The contact sent STOP	Don’t message them until they send START
404	NOT_FOUND	Unknown endpoint or message id	Check the path / id
400 / 403 / 404	REQUEST_FAILED	The send was refused for another reason, e.g. the account was suspended or the number is no longer connected	Read error.message
409	WINDOW_CLOSED	Free-form message outside the 24-hour window	Send a template
429	RATE_LIMITED	Too many requests	Wait and retry — see Rate limits
500	—	Something went wrong on our side	Retry with backoff; contact us if it persists

Two cases have a different body, without the error object: a request body that is not valid JSON (400) and server errors (500). Both look like { "success": false, "message": "…" }.

Failures after acceptance

A 202 means MeAPI accepted the message, not that WhatsApp delivered it. Meta can still reject it — for example an unapproved or paused template, wrong template parameters, a number that isn’t on WhatsApp, or your number’s messaging limit. The message then becomes failed with Meta’s reason in error, visible through message status and message.status webhooks.