Skip to main content
When your server calls the WhatsApp Messages API and something is wrong, Meta returns an error object with a code and message. Knowing what each code means lets you fix the issue immediately.

​
Where errors come from

Type 1 — API error (your call to Meta fails): 
{ "error": { "code": 190, "message": "Invalid OAuth access token" } }
Type 2 — Status webhook failure (Meta can’t deliver): 
{ "statuses": [{ "status": "failed",
    "errors": [{ "code": 131026, "title": "Message Undeliverable" }] }] }

​
Common error codes

CodeMeaningFix
190Access token expired or invalidGenerate a new token in Meta Dashboard
100Invalid parameterCheck phone format (no +, include country code: 919959623255)
131030Number not in test recipientsAdd the number in Meta Dashboard → API Setup
13104724-hour window closedSend a template message instead of free text
131049Marketing message blocked — user limit hitWait, or send a Utility template
131026Number has no WhatsApp or can’t receive messagesVerify the number is on WhatsApp

​
Handling errors in code

try {
  await sendTextMessage(to, text);
} catch (error) {
  const code = error.response?.data?.error?.code;

  const hints = {
    190:    'Token expired — generate a new one.',
    131047: '24h window closed — use a template.',
    131049: 'Marketing blocked — use Utility template.',
    131026: 'Number not on WhatsApp.',
    131030: 'Add number as test recipient in Meta.',
  };

  console.error(`[ERROR] code: ${code} | ${hints[code] || 'check Meta docs'}`);
}

​
Frequently asked

Your access token has expired or is invalid. Go to Meta Dashboard → WhatsApp → API Setup and generate a new temporary token, or create a permanent System User token. See Access tokens.
The 24-hour customer service window is closed. The customer hasn’t messaged you in the last 24 hours. You must send a pre-approved template instead of a free-form text message.
You’re using a test number and the recipient’s phone number isn’t in your test recipient list. Go to Meta Dashboard → WhatsApp → API Setup → add the number under “To”.
WhatsApp blocked a marketing message because that user has already received too many marketing messages from businesses. This is a per-user cap Meta enforces. You cannot override it.

​
Gotchas & common mistakes

  • Phone number format — always send without the + sign: 919959623255 not +919959623255. Wrong format causes error 100.
  • Test mode number restrictions — during development, only numbers you explicitly add as test recipients can receive messages.
  • Token expiry — temporary tokens expire every 24 hours. For production, always use a permanent System User token.