WhatsApp API Error Codes Explained, with Fixes

November 2026 ยท By Jitesh Parmar, founder of JS1 Software

Who this is for

You added WhatsApp to your billing or ERP software. Most invoices go out fine, but some come back with a number like 131026 or 132001, and the user wants to know why their customer did not get the bill.

This page lists the error codes a sender of invoices, reminders and dispatch updates actually meets, what each one means, and what your code should do about it. Every meaning here was checked against Meta's own error codes page in November 2026.

In short: sort every error into one of three buckets. Retry later (rate limits, a temporary fault), fix, then send again (a wrong template, wrong values, a bad file), or never retry (the customer opted out, the number is the sender's own). Retrying the third bucket only repeats the failure.

Where the error shows up

An error reaches you in one of two ways:

  • In the answer to your send call. The request itself was wrong: a bad parameter, an expired token, a template that does not exist.
  • Later, in the status webhook, as a failed status. The send was accepted, then the message could not be delivered.

Either way you get an error with a code, a title, a message and often error_data.details. Two things to know:

  • Build on code and details. Meta says the title will be deprecated, and error_subcode is no longer sent from API version 16.0.
  • Keep the raw code with the invoice. When a customer says "I never got it", the code tells support in ten seconds what happened.

The quick table

Code What it means What to do
131026 Message could not be delivered to this number Fix: check the number with the customer
131047 More than 24 hours since the customer last wrote Fix: send an approved template instead
131049 Not delivered, to keep the customer's inbox healthy Retry, but not before 24 hours
131050 Customer stopped marketing messages from you Never retry marketing to them
131021 Sender and recipient are the same number Never retry: fix the number
131056 Too many messages to this one customer, too fast Retry this customer later
130429 Your account's sending rate limit was hit Retry later, send slower
131048 Your number is restricted for spam reports Stop and check number quality
132000 Wrong number of values for the template Fix the values
132001 Template not found in that language, or not approved Fix the template name or language
132005 Translated text too long Fix the template
132007 Template breaks a WhatsApp policy Fix the template
132012 A value has the wrong format Fix the values
132015 Template paused for low quality Edit it, wait for approval
132016 Template disabled for good Make a new template
131053 The file could not be uploaded Fix the file
131031 Sending account locked or restricted Stop, contact whoever manages it
368 Business account restricted for a policy breach Stop, contact whoever manages it
131042 A billing or payment-method problem Fix billing, then retry
133010 The sending number is not registered Register it, then retry
190 Access token expired Get a new token
131000 Unknown error Retry; if it keeps happening, raise it with support

The rest of this page explains the ones that cause the most confusion.

The customer's number: 131026, 131050, 131021

131026: message undeliverable

This is the one you will see most. Meta gives three reasons: the number is not on WhatsApp, the person has not accepted WhatsApp's latest terms, or they use a very old version of the app.

What to do: do not retry automatically, because the same message to the same number fails the same way. Show it to the user ("Ramesh Textiles: number not on WhatsApp?") so someone phones the party, corrects the number, or sends the bill by email. In a billing screen, a short list of "bills not delivered on WhatsApp" is worth more than any retry loop.

A common cause in India: the party gave a landline or an old mobile years ago and it is still in your customer master. Clean numbers before sending (country code, digits only). Our C# guide has a small function for that.

131050: the customer opted out of marketing

The customer told WhatsApp they do not want marketing messages from your business. Meta's advice is plain: do not retry. Mark the party so your next offer broadcast skips them.

131021: same number as the sender

Someone typed your own business number into the party's mobile field, usually while testing. Fix the master; never retry.

The 24-hour window: 131047

You sent a normal text message (not a template) more than 24 hours after the customer last wrote to you.

The rule: a business can send free-form messages only within 24 hours of the customer's last message. Outside that window, every message your business starts must be an approved template. So your invoice run must always use a template. Free text is for replying to a customer who just wrote.

Not delivered to protect engagement: 131049

This one confuses everyone, because nothing is wrong with your message or the number. WhatsApp limits how many business messages, mainly marketing, one person receives, and decided not to deliver yours this time.

What to do: Meta says wait at least 24 hours before trying again; an immediate resend will fail again. Do not loop on it. If invoices hit this, check your invoice template is classed as utility, not marketing. A utility template that reads like an advert ("Check our new arrivals!") can be re-classed as marketing.

Too fast: 130429, 131056, 131048

These three look alike but need different handling.

  • 130429 (rate limit hit): your whole account is sending faster than the platform allows. Slow the batch down and retry later. A month-end run of 400 invoices should go out at a steady pace, not all in one second.
  • 131056 (pair rate limit): too many messages to one customer in a short time. Other customers are not affected, so keep sending to them and retry only this one after a pause. This usually means a loop sent the same customer several bills at once: send them a little apart.
  • 131048 (spam rate limit): sending from your number has been restricted, most likely because people blocked you or reported your messages as spam. Retrying will not help. Stop, check your number's quality rating in WhatsApp Manager, and look at what you have been sending.

Template errors: 132000 to 132016

Every message your business starts uses a template Meta approved, and these codes mean the template and your values do not fit together.

  • 132000: the number of values you sent does not match the template's placeholders. If the template has {{1}} and {{2}}, send exactly two values.
  • 132001: the template does not exist in that language, or is not approved yet. Check the exact name and the language code: en and en_US are different templates.
  • 132012: a value is not in the format the template asks for. Check what kind of value each placeholder expects.
  • 132005: the translated text is too long. Fix the translation in WhatsApp Manager.
  • 132007: the template content breaks a WhatsApp policy. Read the rejection reason and reword it.
  • 132015: the template was paused for low quality (people blocked or reported it). Edit it to improve it; you can send again once it is approved.
  • 132016: the template was paused too many times and is now disabled for good. Create a new template with different content.

A cause we see often in billing software: the party name or narration holds a line break, a tab or a long run of spaces, copied from an old system. Clean every value to one line before sending.

Files: 131053

The document or image could not be uploaded. Meta points at the file type: check the MIME type is one WhatsApp accepts (application/pdf for an invoice) and the file is not damaged. Name the file after the invoice, such as INV-1043.pdf, because the customer sees that name.

The sending account: 131031, 368, 131042, 133010, 190

These are not about one message. They stop every send until a person fixes them:

  • 131031 and 368: the business account is restricted or disabled for a policy breach (131031 can also mean a wrong two-step PIN). Stop the queue and tell whoever manages the WhatsApp account.
  • 131042: a payment-method problem on the account (no payment method, credit line, currency). Fix billing, then resume.
  • 133010: the sending number is not registered on the platform yet.
  • 190: the access token expired. Get a new one; do not retry with the old.

Your code should notice these and pause the whole queue, not fail 400 invoices one by one. One alert to a person beats 400 identical failures.

Code: sort the error, then act

Put the decision in one place. A small C# function is enough:

public enum ErrorAction { RetryLater, RetryAfterADay, FixThenResend, NeverRetry, PauseEverything }

public static ErrorAction Classify(int code) => code switch
{
    130429 or 131056 or 131000         => ErrorAction.RetryLater,       // rate limits, unknown fault
    131049                             => ErrorAction.RetryAfterADay,   // Meta: wait at least 24 hours
    131050 or 131021                   => ErrorAction.NeverRetry,       // opted out, own number
    131048 or 131031 or 368 or 131042
        or 133010 or 190               => ErrorAction.PauseEverything,  // account-wide: a person must act
    _                                  => ErrorAction.FixThenResend     // 131026, 131047, 132xxx, 131053, ...
};

Then:

  • RetryLater: wait (1, 5, 15 minutes, then hourly), then send again. If the error came in the status webhook, that message is finished, so the retry is a new send (with a new idempotency key, if your API uses one).
  • RetryAfterADay: schedule one more try after 24 hours, and stop after that.
  • FixThenResend: show the code and a plain sentence to the user. A resend after the fix is a new send with a new key.
  • NeverRetry: mark the party, so the next run skips them.
  • PauseEverything: stop the queue and alert a person.

Unknown codes fall into FixThenResend on purpose: an unknown error should reach a person, not loop forever.

Is a failed message charged?

Meta's own rule (from its pricing page): it bills a message only when it is delivered. A message that was sent but not delivered is not billed by Meta.

Your provider may count it differently, and many also charge a monthly platform fee on top, so check both. JS1 Talkback has no monthly fee: you pay only for the messages you send. A send that is refused before it goes out (a template not approved yet, too few values, no balance) is never charged; a message that was sent and then failed, including one refused later for its template, is counted like any other message sent.

Common questions

The number is on WhatsApp, but I still get 131026. Why?

The other two reasons: the person has not accepted WhatsApp's latest terms, or their app is very old. Ask them to update WhatsApp and open it once. Also check the number has the right country code: 9876543210 without 91 is a different number.

Why does 131049 happen on invoices?

It is mainly about marketing. If invoices get it, your template was probably classed as marketing. Keep invoice templates plain and factual: what was billed, the amount, the due date.

Should I retry every failure three times?

No. Only rate limits and unknown faults are worth a quick retry. Retrying a 131050 or a 132001 fails every time, and a 131048 means your number is already restricted: retrying will not lift it.

Where can I see the full list?

Meta's error codes page has every code, including ones a billing sender rarely sees (Flows, payments, groups).

Sending through JS1 Talkback

JS1 Talkback sends invoices, reminders and dispatch updates from your customer's own WhatsApp number, with a REST API for billing and ERP software. Instead of raw numbers, your webhook gets one of five plain failure codes (NOT_REACHABLE, TEMPLATE_REJECTED, DOCUMENT_FAILED, RATE_LIMITED, UNDELIVERABLE), and the inbox shows each failure as a sentence a shop owner can act on.

Walk-throughs: send an invoice PDF from C# and .NET and from PHP and Laravel.

See the developer page and get a free test key.


← Back to all posts