Error 131026 WhatsApp API: Message Undeliverable

What is Error 131026?

Error 131026 indicates that the message cannot be delivered to the recipient. This can be frustrating because it has several different causes.

{
  "error": {
    "message": "(#131026) Message undeliverable",
    "type": "OAuthException",
    "code": 131026,
    "error_subcode": 2494010,
    "fbtrace_id": "..."
  }
}

Common Causes

1. Number is not on WhatsApp

The recipient's number is not registered on WhatsApp or has been deactivated.

Solution: Validate the number before sending:

// Check if number is on WhatsApp
async function checkWhatsAppNumber(phoneNumber) {
  try {
    const response = await fetch(
      `https://graph.facebook.com/v18.0/${phoneNumberId}/messages`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          messaging_product: 'whatsapp',
          to: phoneNumber,
          type: 'template',
          template: {
            name: 'hello_world',
            language: { code: 'en_US' }
          }
        })
      }
    );

    const data = await response.json();
    return !data.error;
  } catch (error) {
    return false;
  }
}

2. User hasn't accepted Terms of Service

The recipient hasn't accepted the latest WhatsApp Terms of Service and Privacy Policy.

Solution: The user needs to open WhatsApp and accept the new terms.

3. Old WhatsApp version

The recipient is using a very old WhatsApp version that doesn't support the API.

Solution: The user needs to update their WhatsApp app.

4. User blocked your number

If the user blocked your business number, messages won't be delivered.

Solution: There's no technical solution. Respect the user's decision.

5. Incorrect number format

The number is in an incorrect format.

Solution: Use international format without symbols:

function formatPhoneNumber(phone, countryCode = '1') {
  // Remove everything that's not a number
  let cleaned = phone.replace(/\D/g, '');

  // Remove leading zero if exists
  if (cleaned.startsWith('0')) {
    cleaned = cleaned.substring(1);
  }

  // Add country code if missing
  if (!cleaned.startsWith(countryCode)) {
    cleaned = countryCode + cleaned;
  }

  return cleaned;
}

// Examples:
// (555) 123-4567 -> 15551234567
// +1 555 123 4567 -> 15551234567

Implementing Error Handling

async function sendWhatsAppMessage(to, message) {
  try {
    const response = await fetch(/* ... */);
    const data = await response.json();

    if (data.error) {
      switch (data.error.code) {
        case 131026:
          // Message undeliverable
          await handleUndeliverable(to, data.error);
          break;
        case 131047:
          // 24h window expired
          await sendTemplateInstead(to);
          break;
        default:
          throw new Error(data.error.message);
      }
    }

    return data;
  } catch (error) {
    console.error('Error sending message:', error);
    throw error;
  }
}

async function handleUndeliverable(phoneNumber, error) {
  // Mark number as invalid/problematic
  await markNumberAsInvalid(phoneNumber, {
    error_code: error.code,
    error_subcode: error.error_subcode,
    timestamp: new Date()
  });

  // Notify your team or system
  await notifySupport({
    type: 'undeliverable_message',
    phone: phoneNumber,
    error: error
  });
}

Error Subcodes

Error 131026 may come with different subcodes:

| Subcode | Meaning | |---------|---------| | 2494010 | Number is not on WhatsApp | | 2494011 | Terms of service not accepted | | 2494012 | App version too old | | 2494013 | Account deactivated |

Best Practices

1. Validate numbers before sending: Maintain a list of validated numbers
2. Implement retry with backoff: Some errors are temporary
3. Monitor failure rate: Many 131026 errors may indicate problems with your contact list
4. Offer alternative channels: Email, SMS as fallback

Retry with Exponential Backoff

async function sendWithRetry(to, message, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await sendWhatsAppMessage(to, message);
    } catch (error) {
      if (error.code === 131026 || attempt === maxRetries) {
        // Don't retry for 131026 (won't help)
        throw error;
      }

      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Conclusion

Error 131026 usually indicates a problem with the destination number, not with your implementation. The best strategy is to proactively validate numbers and have fallbacks for when messages can't be delivered.

Need help with your WhatsApp integration? Contact me for specialized consulting.