Troubleshoot WhatsApp message delivery errors
WhatsApp must be enabled in your Klaviyo account to access delivery data.
Identify and fix WhatsApp delivery errors to improve message performance and protect your sender reputation.
Before you begin
Follow these steps to check your WhatsApp delivery results:
- For a campaign, go to Campaigns and open the sent campaign, then open its WhatsApp message report. For a flow, go to Flows, open the flow, select its WhatsApp message, and click View details.
- On the Overview tab, review the Deliverability section.
- Select Recipient activity > Failed and review the Failed Reason column.
- Open a recipient’s profile and expand the Failed to Deliver WhatsApp event for the message. Find Vendor Error Code in the event details.
If your delivery rate is below 90%, or you see repeated error codes, review the table below and set up the WhatsApp error segment.
Common WhatsApp error codes
Use the following table to identify common WhatsApp error codes and how to resolve them.
Error code | Description | Recommended action |
|---|---|---|
131026 – Message undeliverable | WhatsApp couldn’t deliver the message. Common causes include invalid WhatsApp numbers, missing country codes, or outdated Terms of Service. | • Verify phone number format and country code. |
131053 – Media upload error | The media file in your message couldn’t be uploaded. | • Check file format and compression. |
130472 – Number in experiment | WhatsApp is running experiments that may limit marketing messages to certain users. | • Contact users through another channel and ask them to message your business on WhatsApp. |
131049 – Maintain healthy ecosystem engagement | WhatsApp blocked delivery due to low engagement or frequent marketing messages. | • Avoid immediate retries. |
131050 – Recipient opted out | The recipient turned off marketing messages from your business in WhatsApp. | • Do not resend marketing messages. |
131000 – Unknown error | Temporary or general delivery failure. | • Retry later. |
Why use the WhatsApp error segment
Repeated delivery failures reduce performance and damage your sender reputation. The WhatsApp error segment identifies contacts that meet the failure conditions below so you can exclude them from future WhatsApp campaigns. For details on which messages are charged, see Understand WhatsApp billing in Klaviyo.
This segment must be added manually. It is not automatically applied to campaigns.
When to use it
- Delivery rates are below 90%.
- Errors like 131049, 131026, or 130472 appear frequently.
How to create the WhatsApp error segment
- Go to Audience > Lists & segments and select Create > Segment. Name the segment, for example, WhatsApp delivery errors. If a naming panel opens, click Create segment to continue to the builder.
- Set conditions:
- Select If someone can or cannot receive marketing, then choose can receive and whatsapp marketing.
- Join the consent condition with AND to a group of What someone has done (or not done) conditions. Join the 3 failure conditions below to one another with OR:
- Failed to Deliver WhatsApp > at least once > in the last 16 days, where Vendor Error Code equals 131049.
- Failed to Deliver WhatsApp > at least once > over all time, where Vendor Error Code equals 131026.
- Failed to Deliver WhatsApp > is greater than 2 > over all time, where Vendor Error Code includes any of 130472 and 131049.
- Click Create segment to save the definition.
- In each WhatsApp campaign’s audience settings, select this segment under Don't send to. Click Next, or Save and return if you opened the audience from the campaign canvas, to save the exclusion.
Best practices
- Always exclude the WhatsApp error segment before you send a campaign.
- Regularly review delivery performance and error trends.
- Remove invalid or inactive contacts from your lists.
- Focus on engaged users to maintain a strong sender reputation.