Failed messages

A failed message is one that never reached the customer. Every failure comes with a reason, and the reason tells you whether to wait, fix something, or leave it.

To see them, open a campaign from the Campaigns page and go to its Failed section. You are not charged for failed messages.

What to do, by reason

flowchart TD
    F["Failed message"] --> Q{"What does the reason say?"}
    Q -->|"Unhealthy system activity, experiment, undeliverable"| W["Wait 24 to 48 hours, then resend"]
    Q -->|"Service unavailable, unidentified error"| H["Wait a few hours, then resend"]
    Q -->|"Rate limit, parameter, template, media"| X["Fix the cause, then resend"]
    Q -->|"Not on WhatsApp, or blocked you"| C["Do not resend. Clean the list."]

For how to resend, see Manage broadcasts.

Wait, then resend

These are not about anything you did wrong in this broadcast. They clear with time.

Unhealthy system activity

The failure reason says Unhealthy system activity, or that the message was not delivered to maintain healthy ecosystem engagement.

WhatsApp limits how many marketing messages one person receives from all businesses combined. If a customer has had several already and ignored them, WhatsApp holds back new ones for a while, yours included. The limit is per person, not per business, and WhatsApp does not publish the number. It applies to customers in every country, and occasionally to utility messages as well.

This is the most common reason a broadcast to a good list still has failures, and it gets worse on busy days such as festivals and sale weekends, when every brand is sending.

What to do: wait 24 to 48 hours, then resend to the failed contacts. Resending sooner mostly fails again.

What lowers it over time:

• Only message people who agreed to hear from you, and say at sign-up that you will use WhatsApp.
• End marketing templates with a way to unsubscribe, such as Reply STOP to unsubscribe.
• Send fewer, more useful broadcasts. Messages people engage with keep getting through.
• Keep broadcasts to people who have never heard from you rare.

Part of an experiment

The failure reason says the user's number is part of an experiment.

WhatsApp is running a test on that person's account, and your business is in it. You cannot message them for 24 to 48 hours. Other businesses may still reach them, because the experiment is not the same for every business.

What to do: wait 24 to 48 hours, then resend.

Message undeliverable

Code 131026. The message could not be delivered to that person. The usual causes:

• They use an old version of WhatsApp.
• They have not accepted WhatsApp's latest terms of service.
• They blocked your number.
• WhatsApp held the message back because they rarely engage with business messages.

What to do: try again after 24 hours. If it matters, such as an order update for a customer who is waiting, reach them another way and ask them to update WhatsApp and check they have not blocked your number.

Service unavailable

WhatsApp's own servers were down when the message was sent.

What to do: check the WhatsApp Business Platform status page. Once it shows everything working, resend.

Unidentified error

WhatsApp could not send the message and did not say why.

What to do: resend after a few hours. It usually goes through.

Fix, then resend

These are caused by something in the broadcast or template. Fix it and the resend works.

Rate limit

Code 130429. The broadcast went to more people than your messaging limit had room for. Everyone beyond the limit failed.

You were warned before sending: Audience size exceeding remaining quota, some messages may not be delivered.

What to do: resend to the failed contacts the next day, after your limit resets. In future, keep each day's broadcasts within your limit, and split big audiences over several days. See Messaging limits and quality.

Invalid or missing parameter

The failure reason says Invalid parameter or Required parameter is missing. A variable in the template did not get a proper value.

The parameter was misspelt or used wrongly. A contact with no value for an attribute that has no fallback also fails.

What to do: check each variable, add a fallback to every attribute, and resend. See Broadcast settings.

Template does not exist

Code 132001. WhatsApp could not find the template, either because it is not approved yet or because the name or language does not match an approved template.

What to do: check the template's status is APPROVED, then resend.

Template is paused

Code 132015. WhatsApp paused the template because many people who received it blocked it. Nothing sent with it will be delivered until it is active again.

What to do: write a new version of the template, with the wording changed, and send that instead. Look hard at who you sent the paused one to. See Why templates get rejected.

Media upload error

The image, video or file could not be sent, usually because its type is not supported or it is too big.

What to do: check the file against the limits, 5 MB for images, 16 MB for video and 100 MB for documents, and resend. See Broadcast settings.

Clean your list

Not on WhatsApp, or blocked you

Some numbers are not on WhatsApp at all. Others belong to customers who blocked your number. Both fail every time.

What to do: do not resend. Tag these contacts dnd and add Tags not has dnd to future filters, so they stop counting towards your audience and your limit. See Remove and block contacts.

A few of these in any list is normal. A lot of them means the list itself is poor, such as an old export or numbers collected without asking. Look at its Source before importing anything else from the same place.