WhatsApp Message Not Delivered? Common API Error Codes and How to Fix Them
You send a payment reminder to 500 customers. The dashboard says 430 delivered, 70 failed, and nobody on your team can tell you why. Or a single customer swears they never got their order update, while your system shows it as sent.
On the WhatsApp Business API, a message passes through several checks before it reaches a phone, and each check can fail for a different reason. This guide explains the delivery stages, the most common error codes and what to do about each one.
Sent, Delivered and Read: What Each Status Means
Every API message moves through a few statuses.
Sent: WhatsApp accepted the message from your system. This does not mean the customer has it.
Delivered: the message reached the customer's phone or device.
Read: the customer opened the chat. If the customer has turned off read receipts, you may never see this status even when they have read it.
Failed: WhatsApp could not deliver it, and the status usually comes with an error code.
A message stuck at Sent is normally not a bug. The customer's phone may be switched off, out of coverage or low on storage, and WhatsApp will keep trying for a limited period. Do not resend straight away, or you risk a duplicate.
Error Codes Are Meta's, Not Your Software's
The numeric codes you see come from Meta's WhatsApp Cloud API. A good platform shows them in plain language, but the meaning is the same everywhere. The codes below are the ones Indian businesses run into most. Meta occasionally changes its error documentation, so confirm against the official WhatsApp error code list if a code behaves differently from what is described here.
131047: Re-engagement Message Required
This is the most common failure for new users. It means you tried to send a normal text, image or other free-form message to a customer whose last message to you was more than 24 hours ago.
Outside that window, only an approved template can start the conversation. The fix is to send a template, and once the customer replies, you can talk freely again. Our guide to the 24-hour messaging window explains the rule in full.
131026: Message Undeliverable
This code is a catch-all for a message that could not be delivered to that number. Typical causes:
The number is not on WhatsApp. A landline, a wrong digit or a number that has never registered will fail every time.
The customer is on an old WhatsApp version that cannot receive the message type you sent.
The customer has not accepted WhatsApp's latest terms in the app yet.
Clean your contact list before a campaign. A sheet with typing mistakes and landline numbers is one of the quickest ways to see a high failure count. Our guide to contact management covers keeping the list tidy.
131049: Not Delivered to Maintain Ecosystem Engagement
Meta uses this code when it chooses not to deliver a marketing template to a particular customer, because it expects the person is unlikely to engage with it. It is a quality control by Meta, not an error in your setup.
What helps is better targeting. Send to people who opted in, who bought recently or who asked about the product, and avoid blasting your entire database. If you see this code repeatedly, check your content and audience before you try a resend. Retrying the same message to the same person is unlikely to change the outcome.
130429 and 131056: Rate Limits
These codes mean you are sending too fast, either overall or to the same customer. WhatsApp throttles throughput per number, and it also limits repeated messages to one recipient in a short window.
Spread large campaigns over a longer period instead of firing everything at once, and do not send the same customer several messages back to back. A decent broadcasting tool queues messages for you. See broadcast messaging for how scheduling works.
131048: Spam Rate Limit
This one is serious. It means too many recent messages from your number were blocked or reported by customers, so WhatsApp limits what you can send. It is closely tied to your quality rating and daily messaging tier, which we cover in WhatsApp quality rating and messaging limits.
Pause marketing sends, review who you are messaging and why, and fix opt-ins before you start again.
132000, 132001 and 132012: Template Problems
Template errors are almost always preventable.
Parameter count mismatch: your template has three variables and the request supplies two.
Template does not exist or is not approved: the name is misspelt, the language code is wrong or the template is still pending, rejected or paused.
Parameter format mismatch: a variable that should hold a date or number contains something different from what the template expects.
Test every template with a sample record before a bulk run. Our guide to template approval best practices lists what makes templates pass review, and the template builder helps you preview the final message.
Payment and Account Errors
If every message starts failing at once, the problem is rarely the content. Look at the account itself:
No payment method or credit on the WhatsApp Business Account can block template sends. Check the billing section of Meta Business Manager, or your provider's wallet, if you use one.
The number is restricted or disconnected. A quality drop, a policy violation or a pending phone number registration issue can all pause sending.
An expired or revoked access token on a custom integration stops requests entirely. A platform like VedLink AI manages this connection for you.
A Step-by-Step Checklist When a Message Fails
1. Read the exact code. Do not guess from the word Failed. The code narrows the cause to a few possibilities.
2. Check whether the customer is inside the 24-hour window. If not, you need a template.
3. Confirm the number is valid and on WhatsApp. Try the click-to-chat link for that number from a phone.
4. Check the template status. It must be approved and the variables must match.
5. Look at your quality rating and tier. A drop often explains sudden failures across many contacts.
6. Review the audience. Were these people opted in and recent customers?
7. Retry only after fixing the cause. Blind resends add cost and annoy customers.
Example: A Clothing Store Sending an Offer
Say a clothing store sends a sale template to 2,000 contacts exported from an old register. Some numbers have a missing digit, some belong to landlines and some people never opted in. The report shows a mix of 131026 and 131049 failures. The right response is not a resend. It is to clean the list, remove numbers that failed twice, split the audience by recent purchase and send a smaller, more relevant batch next time. This is an illustration, and your own failure mix will differ.
How to Reduce Failures Before They Happen
Collect numbers properly. Capture them with opt-in at billing, on forms and through click-to-chat links, so the numbers are real and consented.
Validate numbers at entry. Standardise on 10-digit Indian numbers with the country code 91.
Segment campaigns. Send to engaged groups first. Read our guide on WhatsApp contact segmentation.
Test templates with one or two staff numbers before the full run.
Watch the dashboard. If your delivery rate falls sharply mid-campaign, stop and investigate instead of finishing the batch.
Frequently Asked Questions
Why does the message show Sent but never Delivered? The customer's phone may be off or offline, the number may not be on WhatsApp, or the user may have blocked your business. WhatsApp does not tell you which.
Can I find out if a customer blocked me? Not directly. A pattern of undelivered messages to one number, along with no replies, is a hint but not proof.
Will failed messages be charged? Generally Meta charges for delivered messages, not failed ones. Billing rules change, so check the current rate card, and see our API pricing explainer.
Should I resend failed messages automatically? Only for fixable causes such as a template mistake. Automatic retries on blocked or invalid numbers are a waste.
Final Thoughts
Most delivery failures come down to four things: the 24-hour window, bad numbers, template mistakes and poor targeting. Learn to read the code, fix the cause and keep your lists clean, and your delivery rate will take care of itself. If you want these reports and retries handled inside one dashboard, you can see the plans on our pricing page.