Official WhatsApp API Errors: Distinguishing Your Problem from Meta's Rejection

Database and recipient errors

These appear scattered throughout the campaign, in similar proportions from one campaign to another, and relate to the company’s records — not the sending.

• Number without a WhatsApp account. The phone exists but doesn’t use the app. There’s nothing to resend. The value is in marking the contact so you don’t pay for it every month.
• Number in invalid format. Missing country code, extra character, field came from a spreadsheet with mask. It’s rejected before sending.
• Brazilian cell phone spelling. A particular and tricky case: old numbers stored without the ninth digit, or with a digit not used in that region. WhatsApp itself decides which spelling exists, and the only correct way is to check before sending rather than guessing by digits.
• Expiration. The message waited for the device to appear and the deadline expired. It’s not an invalid number — it’s an absent device. Resending at another time usually recovers a good portion.
• Blocked by recipient. That person blocked the company. It’s definitive and the record must be marked, or the list keeps paying and quality degrades.

Platform rejections

Here is the group that most causes wrong decisions because the returned message looks like a defect but isn’t.

• Message could not be delivered. Generic rejection, no detailed reason. Could be anti-fraud filter, recipient behavior, or internal criteria. Do not resend.
• Number in platform experiment. Meta separates user segments for internal tests and rejects sends to them. It’s unrelated to the company or database and doesn’t change with insistence.
• Template paused for quality. That specific model accumulated blocks and was suspended. The number remains healthy and other templates work — changing the number doesn’t solve it, rewriting the message does.
• Policy restriction. Content the platform doesn’t accept, even with an approved template.

The typical confusion: the team sees many of these rejections, concludes "the number is burned," and migrates the campaign to another number. The campaign restarts, the same rejections appear, and now two numbers have worse quality. The right path is to check what the platform is rejecting, accept the portion that doesn’t depend on the company, and review content when the proportion rises.

The window and the template: the costliest confusion

Much of the failures in new operations come from a single misunderstanding about when each type of message can be used.

When the customer writes to the company, a service window opens — commonly 24 hours — during which the company can reply with free-form messages however it wants. Outside this window, free-form messages are rejected, and the only path is an approved template.

The two mirrored errors:

• Trying free-form message outside the window. Happens when automation replies to an old contact, or when an agent opens an archived conversation and writes. The rejection mentions the window, and the fix is to use a template.
• Using a template with the window open. Doesn’t fail but wastes money and sounds robotic to someone who just wrote.

There is a variation that confuses even more: on Instagram Direct and Messenger, the window logic also exists with its own rules. A lock written thinking only about WhatsApp ends up blocking legitimate replies on other channels — the customer wrote, the window is open, and the system rejects because it applied the wrong rule. The channel of that conversation is the authority.

Limit, quota, and quality

Three different things that teams often call by the same name.

The limit on initiated conversations is the cap on how many new contacts that number can open in a period. It increases as the operation demonstrates volume and quality. When reached, the failure appears mid-campaign — it starts well and degrades.

The number quality is a platform indicator based on blocks and reports. Low quality doesn’t by itself prevent sending but usually comes with limit restrictions and is the alarm before serious problems.

The financial pending is the quietest: a commercial account with an open invoice can have sends blocked even with a green number and approved template. The failure doesn’t say "open invoice" — it says something generic — and the team spends hours looking for technical defects. It’s worth checking before any long investigation.

Media and header errors

Templates with image, video, or document in the header have their own category of failures, often misdiagnosed because the returned phrase mentions parameters.

• Format not accepted. Exotic image format, PNG with transparency or unusual color profile, file extension not matching content.
• Size above limit. Each media type has its own cap.
• Media identifier from another number. Files sent to the platform are associated with the sending number. Using that identifier on another number fails — again, rotation runs into this.
• Expired media address. Links to files hosted by the platform have short validity and can’t be used for later resends.

A design principle is golden here: media preparation should not block sending. If image conversion fails but the original file is already in an accepted format and within size limits, the right approach is to proceed with the original and let the platform decide — not stop the entire campaign due to an auxiliary step.

What can and cannot be resent

The mental table that avoids most damage:

• Resend after fixing: wrong template, invalid parameter, wrong language, missing permission, expired token, server network failure.
• Resend after a delay, at another time: expiration due to absent device.
• Never resend: generic platform rejection, number in experiment, blocked by recipient, number without WhatsApp account, policy restriction.

And a golden automation rule: automatic resend loops are forbidden. A system that retries on its own without classifying the reason turns an isolated rejection into hundreds of attempts against the same recipient — exactly the pattern the platform punishes.

How to build a decision-making error dashboard

A useful dashboard has four characteristics, none of which are technical.

First: message in Portuguese. Numeric codes and English phrases mean nothing to operators. "Failed to send message because this user's phone number is part of an experiment" needs to appear as "Meta blocked this number because it’s part of an internal test." The original text can be stored for investigation but should not be shown on the screen.

Second: grouping by reason, with counts. Thirty identical lines are not thirty problems; they are one problem with thirty occurrences.

Third: classification by group — configuration, database, or platform — so the decision comes from the dashboard itself.

Fourth: suggested action by group. Resend, clean records, fix configuration, or accept. Without this, every error becomes a support ticket.

A campaign in numbers

An example campaign with 3,173 contacts shows how classification changes interpretation.

The dashboard without grouping shows 130 red lines and the team concludes "the campaign failed." Grouped, the picture is different:

• 62 numbers without WhatsApp account — 2.0% of the database
• 34 generic platform rejections — 1.1%
• 19 expirations due to absent device — 0.6%
• 11 numbers in platform experiment — 0.3%
• 4 blocks — 0.1%

There are 130 failures in 3,173, or 4.1% — a normal level. And the decisions are three, not one: 62 contacts are removed from the database and stop costing; 19 are scheduled for resend at another time; and the 49 remaining are platform rejections with no action. No line in this report justifies changing the number, rewriting the template, or opening a ticket — which is exactly what would have happened with the 130 loose red lines.

Five mistakes when handling errors

• Resending what the platform rejected. The result is the same and the number’s quality drops with each attempt.
• Changing numbers due to platform rejection. Transfers the problem to the new number and now two have bad history.
• Letting the campaign run with high failure from the start. Configuration failures aren’t discovered by insisting; they’re discovered by stopping.
• Showing Meta’s text on the operator’s screen. Error in English doesn’t produce decisions — it produces tickets.
• Looking for technical defects before checking the account. Open invoice and missing permission cause failures that look like bugs and are resolved in the Meta dashboard.

Key metrics to monitor

Five indicators keep the operation under control. The total failure rate per campaign, compared to the company’s historical average, is the simplest alarm. The composition of failures by group — configuration, database, and platform — shows who needs to act. The percentage of invalid contacts in the database, which only decreases with record work and costs money in every campaign. The block rate, the most sensitive indicator, which precedes number quality decline. And the amount of automatic resends triggered, which should be near zero for platform rejections — when this number grows, the system is working against the operation itself.