Zanii
Menu

WhatsApp Cloud API error codes, explained

What each code actually means, what causes it in practice rather than in the documentation, and whether retrying will help. Written from operating the thing, not from Meta's reference.

Start freeRead the guides

The 24-hour window

131047

Re-engagement messageRetrying will not help
What it means
More than 24 hours have passed since the customer's last message, so a free-text reply cannot be delivered.
What actually causes it
Almost always an automation replying late — a nightly sync, a queued job, a human who came back to the conversation the next morning. It is not a rate limit and not an account problem, which is what most people first assume.
What to do
Send an approved template instead. If the customer replies to it, a fresh 24-hour window opens. A console worth using should make this error unreachable by checking the window before it accepts a keystroke, rather than reporting it after the message is written.

131051

Unsupported message typeRetrying will not help
What it means
The message type you sent is not supported on this endpoint or for this recipient.
What actually causes it
Usually an interactive message — a list, a catalog, a flow — sent outside the 24-hour window. Interactive messages are free-form by definition, so the window rule applies to them exactly as it does to text.
What to do
Check the window first. If it is closed, only a template will deliver — and a template cannot contain a catalog or a flow launcher, so the sequence is template, customer replies, then the interactive message.

Templates

132000

Template param count mismatchRetrying will not help
What it means
The number of variables you supplied does not match the number the approved template expects.
What actually causes it
Somebody edited the template and the sending code was not updated, or a variable was left empty and dropped from the array. Meta counts positions, not names — an empty string still occupies a position, a missing element does not.
What to do
Send an empty string for a variable you have no value for rather than omitting it. Better: fetch the approved template's own parameter count rather than trusting a hard-coded number that drifts the first time somebody edits the wording.

132001

Template does not existRetrying will not help
What it means
No template with that name and language exists on the WhatsApp Business Account you are sending from.
What actually causes it
The single most misdiagnosed code. **There is no shared template pool at Meta** — approval is per WhatsApp Business Account. A template approved on your first account genuinely does not exist on your second, so a business with five portfolios has five separate copies and five separate review states.
What to do
Check the language code exactly — `en` and `en_US` are different templates. Then check which account you are sending from. If the template really is missing there, create it, subject to the 100-per-account-per-hour ceiling.

132005

Template hydrated text too longRetrying will not help
What it means
The template with your variables filled in exceeds the character limit.
What actually causes it
The template passed review at 900 characters and one customer has a 200-character address. The limit applies to the filled message, not the template, so it fails for some recipients and not others — which makes it look intermittent.
What to do
Truncate long variable values before sending, and leave headroom in the template itself. A body written to 700 characters survives a long name and a long address; one written to 1,020 does not.

132015

Template pausedRetrying will not help
What it means
Meta has paused this template because recipients marked it as spam or blocked the number after receiving it.
What actually causes it
Quality feedback, not a technical fault. A paused template is the first rung of an escalation that ends in the template being disabled permanently and, if it continues, the number's quality rating falling far enough to lower your messaging tier.
What to do
Do not resubmit the same wording. Work out why people marked it — usually it went to a list that did not expect it, or it was marketing dressed as utility. Fix the audience or the category, then rewrite.

Delivery and policy

131049

Meta chose not to deliver this messageRetrying will not help
What it means
A healthy-ecosystem limit: Meta decided this specific marketing message would not improve the recipient's experience.
What actually causes it
Per-user marketing frequency. The recipient has had enough marketing from businesses recently — not necessarily from you. It is silent, it is per recipient, and it is not published as a number anywhere.
What to do
Nothing to retry. Reduce marketing frequency to your list, and check that your utility templates are genuinely categorised as utility — utility is not subject to this limit, and a mislabelled utility message loses that protection as well as costing more.

131026

Message undeliverableRetrying will not help
What it means
The recipient cannot receive the message.
What actually causes it
The number is not on WhatsApp, is an old number that has been recycled, or the recipient's app is too old to render what you sent. In a campaign this is the code that reveals how stale a contact list has become.
What to do
Do not retry the same number. Treat a run of these as a list-hygiene signal — a campaign with 8% undeliverable has a data problem, not a delivery problem.

131048

Spam rate limit hitRetrying may help
What it means
The number's quality rating has fallen far enough that Meta is restricting its sending.
What actually causes it
Blocks and spam reports from recipients, accumulated over days. This is the visible symptom of a problem that started earlier — the quality rating went from green to yellow to red and nobody was watching.
What to do
Stop marketing sends on that number immediately and let the rating recover, which takes days. Then find the campaign that caused it. Watching the quality rating per number is the cheap version of this; discovering it from 131048 is the expensive one.

Numbers, media and authentication

133010

Phone number not registeredRetrying may help
What it means
The number exists in your account but has not completed registration on the Cloud API.
What actually causes it
Verification was completed but the registration call was never made, or two-step verification is still enabled from the number's previous life on the WhatsApp Business app — which you cannot disable once that app is uninstalled.
What to do
Register the number with its six-digit PIN. If two-step verification is the blocker and the app is gone, you have to go through Meta support — which is the reason to disable it *before* migrating, not after.

131052

Media download errorRetrying may help
What it means
Meta could not download the media at the URL you gave, or could not process it.
What actually causes it
A URL behind authentication, a redirect, a slow origin, or a file whose actual type does not match its extension. Meta fetches it server-side with a short timeout and no cookies.
What to do
Upload the file to Meta first and send the resulting media id instead of a URL. The id is usable for 30 days — which means a campaign scheduled further out than that fails at send, after the schedule has already run.

131053

Media upload errorRetrying will not help
What it means
The file was rejected at upload.
What actually causes it
Over the per-type size cap, or an unsupported format. The caps are 5 MB for an image, 16 MB for video and audio, 100 MB for a document — and 100 KB for a static sticker, which is the one that surprises people.
What to do
Check the size before the upload starts rather than after the whole body has transferred. On a 90 MB video over an office connection that check saves several minutes per attempt.

130429

Rate limit hitRetrying may help
What it means
You are sending faster than the API accepts.
What actually causes it
Throughput, not volume — distinct from the messaging tier, which counts unique recipients per 24 hours. This one is messages per second, and a campaign loop with no pacing hits it within seconds.
What to do
Back off exponentially and retry — this one is genuinely transient. A campaign runner should pace itself rather than discovering the ceiling; anything that retries immediately in a loop makes it worse.

A code that is not here?

Send us the code and we will add it. This page is built from what we actually hit in production, so a code you have seen deserves to be on it.

Contact us