Per-User Marketing Limit (Error 131049)

WhatsApp limits how many marketing template messages one person can receive from businesses in a given period. When a person has hit that limit, your marketing message to them is not delivered, and you get error 131049: "This message was not delivered to maintain healthy ecosystem engagement."

This is why a campaign can reach most of your list and still fail for a few people. Nothing is wrong with your template, your number or your account. Those particular people have already had enough marketing messages for now, so WhatsApp holds back more of them. You cannot switch it off. You can wait and try again later.

What the limit is and why it exists#

WhatsApp may limit the number of marketing templates a person receives from any business (not just from you) when that person is less likely to be receptive to them. WhatsApp decides this from several signals, including:

• how many of the marketing messages that person has read recently (their marketing read rate), and
• how many messages they currently have in their inbox from friends, family and businesses.

The limit is not a fixed number. It adapts automatically to each person's recent engagement, so the same person may get fewer marketing messages in a quiet period and more when they are engaging again. Meta says your ability to reach people when they are most engaged does not change.

Meta also notes that if a person taps Not interested in WhatsApp's Offers and announcements setting for your business, it can affect the per-user marketing limit between you and that person.

Which messages count#

If a person replies to one of your marketing messages, that reply opens a 24-hour customer service window. Marketing templates you send inside that window do not count toward their limit.

Meta's rule is written about marketing template messages only. It does not list utility or authentication templates.

What to do when you get 131049#

1. 1

   Don't resend straight away

   Resending to the same person within 24 hours will most likely fail again with another error. It also makes your campaign delivery reports less accurate.

2. 2

   Wait at least 24 hours

   Meta's rule is to wait at least 24 hours before resending a marketing template to a person who has reached their limit. The limit can stay in effect for different lengths of time for different people, so a resend after 24 hours can still fail.

3. 3

   Avoid repeated retries

   If your account tries again and again within 24 hours to send marketing messages to people who have already hit their limit, WhatsApp can block further delivery attempts to those people for up to 24 hours, again with error 131049. This only affects those people. You can still send marketing messages to everyone else.

4. 4

   Get the person to reply

   A reply from the person opens a 24-hour customer service window, and marketing templates sent inside that window don't count toward the limit.

131049 vs. 131050#

These two codes both affect marketing messages, but they mean different things:

To know when a person stops or resumes marketing messages from you, subscribe to the user_preferences webhook. See Error Handling & Codes for other codes.

United States phone numbers#

Separately from the per-user limit, WhatsApp does not currently deliver marketing template messages to people with US phone numbers (a +1 dialing code with a US area code). Sending a marketing template to a US number returns an error.

How it shows up in webhooks#

When a marketing template isn't delivered because of the per-user limit, or because you retried too often for a person who had reached it, Meta sends a messages webhook with a status of failed and error code 131049. This is Meta's own example of that status webhook:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
                "status": "failed",
                "timestamp": "1751142888",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 131049,
                    "title": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "message": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "error_data": {
                      "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
                    },
                    "href": "/documentation/business-messaging/whatsapp/support/error-codes"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Match the failure to the message you sent using statuses[].id (the message ID your send request returned) and recipient_id. Build your retry logic on the code value (131049), not the title text. Meta recommends handling errors by code and details, because titles will eventually be deprecated. See Status Webhooks for the other status values.

A simple handling rule:

for (const status of value.statuses ?? []) {
  if (status.status !== 'failed') continue;
  for (const err of status.errors ?? []) {
    if (err.code === 131049) {
      // Per-user marketing limit: schedule a retry for this recipient
      // no sooner than 24 hours from now. Don't retry in a loop.
      scheduleRetry(status.recipient_id, status.id, { notBefore: Date.now() + 24 * 60 * 60 * 1000 });
    }
    if (err.code === 131050) {
      // Recipient stopped marketing messages from you: do not retry.
      markMarketingStopped(status.recipient_id);
    }
  }
}

Frequently asked#

Gotchas & common mistakes#