0 App user could not be authenticated
What actually causes it
The token expired, was invalidated, or the app user changed a privacy or app setting that blocks access.
What to do
Issue a new access token and verify the app user still grants access.
FREE DEVELOPER REFERENCE · NO SIGNUP
WhatsApp API error codes, decoded
Search every row in Meta's current WhatsApp Business Platform error reference. Each entry tells you what actually triggers the code and what to check next—not just the title Meta returns.
94 documented error cases 11 error groups 8 webhook reason values
Scope: every row listed in Meta's WhatsApp-specific reference as checked on 13 August 2026. The Cloud API sits on Graph API, so an endpoint can also return a generic Graph API error not listed on that WhatsApp page.
ERROR LOOKUP
Find the code before you retry it
Search a code, title, symptom or cause. Repeated codes remain separate because the same number can mean different things in different operations.
Showing all 94 documented cases
Authorization
Tokens, permissions and endpoint eligibility.
3 Capability or permission problem
What actually causes it
The token does not carry a permission required by this endpoint, or the app cannot use the capability.
What to do
Inspect the token with Meta's Access Token Debugger and compare its permissions with the endpoint requirements.
10 Permission missing, removed or endpoint unavailable
What actually causes it
A required permission is absent or revoked; the app may be ineligible for the endpoint. For a Flow endpoint public key, the phone number may not be allowlisted.
What to do
Debug the token, confirm product eligibility, and check the Flow phone-number allowlist when applicable.
190 Access token expired
What actually causes it
The access token is no longer valid, most commonly because its lifetime ended.
What to do
Generate and use a new token.
200 No access token supplied
What actually causes it
Certain GET endpoints received no token and return “Provide valid app ID”; other endpoints can report 190 or 104 for the same omission.
What to do
Add a valid access token to the request. Do not treat this as the expired-token case.
200–299 Permission range
What actually causes it
The endpoint's required permission was never granted or has since been removed.
What to do
Use the Access Token Debugger and restore the exact permission required by the endpoint.
Integrity and enforcement
Policy restrictions, country restrictions and locked accounts.
368 WABA restricted or disabled
What actually causes it
Meta restricted or disabled the WhatsApp Business Account for a platform-policy violation.
What to do
Open the account's policy-enforcement details and resolve or appeal the recorded violation.
130497 Country messaging restriction
What actually causes it
The business category is not permitted to message users in the recipient's country.
What to do
Check the WhatsApp Business Messaging Policy for the category and country; do not retry to an ineligible destination.
131031 Account locked
What actually causes it
The WABA is policy-restricted, disabled, or the request data does not match account data—for example, an incorrect two-step verification PIN.
What to do
Check Policy Enforcement and the Health Status API, then correct any mismatched account data before retrying.
Template creation
Validation failures while creating or editing message templates.
2388039 Template status cannot be changed
What actually causes it
An edit was attempted while the template is in a non-editable status, commonly while review is still pending; daily edit limits also apply.
What to do
Wait for approval or rejection, then edit only when the status permits it.
2388040 Character limit exceeded
What actually causes it
At least one template field is longer than Meta allows for that component or format.
What to do
Use the response details to identify the field and shorten it to the stated limit.
2388047 Header format invalid
What actually causes it
The header component does not follow the accepted format for its selected header type.
What to do
Read the response details, then correct the header type, content or variable formatting.
2388072 Body format invalid
What actually causes it
The message body contains formatting or variables that fail template validation.
What to do
Use the response details to locate and repair the invalid body formatting.
2388073 Footer format invalid
What actually causes it
The footer contains a value or formatting pattern Meta does not accept.
What to do
Use the response details to correct or remove the invalid footer content.
2388293 Too many parameters for the words
What actually causes it
The template has more variables than its amount of fixed explanatory text can support.
What to do
Remove variables or add enough fixed text to make each variable's meaning clear.
2388299 Leading or trailing parameter
What actually causes it
A variable appears at the very beginning or end of the template.
What to do
Place fixed contextual text before the first variable and after the last one.
Template inventory
Account-level limits encountered while adding templates.
2388019 Message-template limit exceeded
What actually causes it
The WABA already has the maximum number of message templates allowed for its current limit.
What to do
Delete templates that are no longer needed or review Meta's current template-limit rules before adding another.
Phone migration
Errors returned while moving a business phone number between WABAs.
2388012 Phone number already in destination list
What actually causes it
The number being migrated is already attached to the destination WhatsApp account.
What to do
Use a number that is not already present or inspect the existing attachment instead of migrating it again.
2388091 / 2388093 Registration code unavailable for this migration
What actually causes it
The ownership-verification API was called for a number that Meta does not consider to be in the migration flow.
What to do
Use the normal phone registration and verification process.
2388103 Destination webhooks missing
What actually causes it
No app is subscribed to webhooks on the destination WABA.
What to do
Subscribe the destination WABA to the app's webhooks, then retry the migration.
2388103 Number should be added, not migrated
What actually causes it
Meta considers the number eligible for direct registration, so the migration API is the wrong flow.
What to do
Register and verify the phone number directly.
2388103 Display name not approved
What actually causes it
The number lacks an approved display name or still has a pending display-name change.
What to do
Obtain display-name approval and clear any pending name change before migrating.
2388103 Source WABA not set up correctly
What actually causes it
The source WABA or its messaging-on-behalf-of relationship is not approved; it may use the deprecated OBO ownership model.
What to do
Confirm both approvals. Contact Meta support if the account still uses the deprecated ownership model.
2388103 No payment account
What actually causes it
The WABA has no active credit line for post-migration messaging.
What to do
Set up an active credit line and share it with the business customer.
2388103 Unspecified migration failure
What actually causes it
Meta could not complete the number migration but did not expose a more specific cause in this row.
What to do
Retry later; if it repeats, keep the trace ID and contact Meta support.
2388103 Different Business Manager owner
What actually causes it
The source and destination WABAs do not represent the same business.
What to do
Choose a destination WABA that messages for the same business as the source.
2388103 Destination WABA not approved
What actually causes it
The destination WABA has not completed the required business verification and account review.
What to do
Complete business verification and wait for the WABA review status to become approved.
2388103 Messaging For request not approved
What actually causes it
The destination WABA's client has not accepted the Messaging For relationship.
What to do
Ask the client to approve the request in Meta Business Suite.
2494100 Account in maintenance mode
What actually causes it
The business phone number is temporarily under Meta maintenance.
What to do
Wait a few minutes, then retry.
Template insights
Availability and configuration of template analytics.
200005 Template insights unavailable
What actually causes it
Meta has not made template insights available for this WABA yet.
What to do
There is no account-side switch that can force availability; check again later.
200006 Template insights cannot be disabled
What actually causes it
The WABA already enabled template insights, and Meta does not permit turning the feature off afterward.
What to do
Leave insights enabled; the operation is irreversible for this account.
200007 Template insights not enabled
What actually causes it
An insights-dependent operation was requested before the WABA enabled template insights.
What to do
Enable template analytics first, then retry.
WhatsApp Business Account
Legacy OBO ownership and transfer failures.
2593079 WABA already marked for another migration
What actually causes it
The account has already been assigned to migrate to a different solution ID under the deprecated OBO model.
What to do
Contact Meta support; do not create a competing migration attempt.
2593085 WABA ineligible for OBO mobility
What actually causes it
The WABA is already customer-owned under sharing, or the customer has not accepted the OBO request.
What to do
Confirm ownership and acceptance, then contact support because OBO ownership is deprecated.
Business app synchronization
Contact and message-history sync limits during onboarding.
2593107 Synchronization call limit exceeded
What actually causes it
The number already used its one contacts sync or one messaging-history sync call.
What to do
Offboard and re-onboard the customer before attempting a new synchronization.
2593108 Synchronization window expired
What actually causes it
The request was made more than 24 hours after onboarding the WhatsApp Business app user.
What to do
Offboard and re-onboard the user, then synchronize inside the 24-hour window.
Rate limits and throttling
App, WABA, throughput, quality and pair-rate controls.
4 App API-call limit reached
What actually causes it
The Meta app exceeded its application-level API request allowance.
What to do
Confirm the limit in App Dashboard, reduce request frequency or volume, and retry after the limit recovers.
80007 WABA rate limit reached
What actually causes it
The WhatsApp Business Account exceeded its allowed API request rate.
What to do
Reduce WABA-level request volume and retry later with backoff.
130429 Cloud API throughput reached
What actually causes it
The sender reached its message-throughput ceiling, independent of ordinary Graph API call limits.
What to do
Queue and slow sends, then retry after capacity becomes available.
131048 Spam or quality restriction
What actually causes it
Meta restricted sends from the phone number after prior messages were blocked or reported as spam.
What to do
Stop bulk retries and inspect the phone number's quality status and template quality in WhatsApp Manager.
131056 Sender–recipient pair rate limit
What actually causes it
The same sender sent too many messages to the same recipient in a short period.
What to do
Pause messages to that recipient; other recipients can still be messaged.
133016 Too many registration attempts
What actually causes it
The number hit its registration or deregistration attempt limit and is temporarily blocked.
What to do
Wait for the block to clear before trying registration again.
131064 Messaging limit from classification violations
What actually causes it
Repeated template-category violations triggered a temporary account messaging limit that affects templates and direct-send messages.
What to do
Correct template classifications and wait for Meta's enforcement period to end.
Cloud API and messaging
Request, delivery, media, template-send, Flow, registration and payment failures.
1 Invalid request or possible server error
What actually causes it
The request is malformed, does not meet the endpoint contract, or Meta is experiencing a server problem.
What to do
Check platform status first, then validate the request against the endpoint reference.
2 Temporary outage or overload
What actually causes it
A Meta service is down or overloaded.
What to do
Check platform status and retry with backoff after service recovers.
33 Business phone number deleted
What actually causes it
The phone number ID refers to a business number that was deleted.
What to do
Confirm that the ID points to an existing business phone number.
100 Unsupported or misspelled parameter
What actually causes it
A parameter name is unknown, misspelled, too long, or invalid for the endpoint. Flow public keys can also cause this when they are not valid 2048-bit RSA PEM keys.
What to do
Compare names, types and limits with the endpoint reference; also verify the stored phone-number ID and Flow key when relevant.
130403 Business blocked the user
What actually causes it
The sending business has blocked the intended recipient on WhatsApp.
What to do
Do not retry until the business explicitly unblocks that user.
130472 Excluded by experiment
What actually causes it
Meta withheld the message because the recipient is in a marketing-message experiment cohort.
What to do
Treat it as not sent and consult Meta's Marketing Message Experiment rules.
131000 Unknown send failure
What actually causes it
Meta could not classify the send failure. For a Flow public key operation, signature calculation, GraphQL access, or the GraphQL response may have failed.
What to do
Retry once; if it persists, preserve the trace ID and open a Meta support ticket.
131005 Permission missing or removed
What actually causes it
The token lacks a permission required by the operation.
What to do
Inspect the token and restore the endpoint's required permission.
131008 Required parameter missing
What actually causes it
A mandatory request field was omitted.
What to do
Add the missing field named in details and verify all endpoint requirements.
131009 Invalid parameter value
What actually causes it
A supplied value is outside the endpoint's supported values, or the referenced phone number is not correctly attached.
What to do
Use error details to identify the value, then compare it with the endpoint and phone-number setup documentation.
131016 Service temporarily unavailable
What actually causes it
A dependency needed for the operation is temporarily unavailable.
What to do
Check platform status and retry later with backoff.
131021 Sender equals recipient
What actually causes it
The destination phone number is the same as the sending business number.
What to do
Send to a different WhatsApp number.
131026 Message undeliverable
What actually causes it
Meta uses this bucket when the destination is not a WhatsApp number, the user has not accepted current terms, or the user's WhatsApp client is too old.
What to do
Using another channel, ask the recipient to message the business, accept current terms and update WhatsApp. The code does not reveal which cause applied.
131037 Test 555 number lacks approved name
What actually causes it
The 555 test business phone number does not have an approved display name.
What to do
Change the number's display name and obtain approval.
131042 Payment method problem
What actually causes it
Billing is incomplete or unusable: no attached payment account, exhausted or inactive credit line, deleted or suspended WABA, missing timezone or currency, or an unapproved Messaging For request.
What to do
Open WABA billing and fix the specific account, credit-line, currency, timezone or relationship issue shown there.
131045 Phone registration error
What actually causes it
The sender number is not registered correctly for the WhatsApp Business Platform.
What to do
Register the phone number, then retry the message.
131047 Outside the 24-hour service window
What actually causes it
The recipient has not replied to this sender in the last 24 hours, so a free-form service message is not allowed.
What to do
Use an approved template to re-engage the recipient.
131049 Healthy-ecosystem delivery limit
What actually causes it
Meta suppressed a marketing template under its per-user marketing-message limits.
What to do
Do not retry immediately; wait at least 24 hours and expect the limit duration to vary.
131050 Recipient stopped marketing messages
What actually causes it
The user opted out of marketing templates from this business.
What to do
Suppress marketing sends to that recipient and use the user_preferences webhook to track a later opt-in.
131051 Unsupported message type
What actually causes it
The payload requests a message type the Cloud API does not support.
What to do
Change the payload to a currently supported message type.
131052 Could not download inbound media
What actually causes it
Meta could not retrieve the media attached to the user's inbound message.
What to do
Read webhook error details and ask the user through another channel to resend or share the file another way.
131053 Could not upload outbound media
What actually causes it
The media upload failed, commonly because the file's real MIME type or format is unsupported.
What to do
Inspect the file itself—not only its extension—and use a supported MIME type and format.
131057 WABA maintenance mode
What actually causes it
The account is temporarily under maintenance, which can occur during a throughput upgrade.
What to do
Wait until maintenance ends before retrying.
131063 Marketing disabled on Cloud API
What actually causes it
The WABA setting disable_marketing_messages_on_cloud_api is true while the template is categorized as marketing.
What to do
Send through the Marketing Messages API or re-enable marketing templates on Cloud API.
132000 Template variable count mismatch
What actually causes it
The send payload provides a different number of parameter values from the template's declared variables.
What to do
Supply exactly one correctly ordered value for every template variable.
132001 Template or language not found
What actually causes it
The named template is unapproved, absent, or unavailable in the requested locale.
What to do
Confirm approval status, exact template name and exact language code.
132005 Translated text too long
What actually causes it
The selected translation exceeds a component limit or is not in a usable translated state.
What to do
Inspect that language version in WhatsApp Manager and shorten or complete the translation.
132007 Template violates policy
What actually causes it
Meta's review determined that the template content breaches a WhatsApp policy.
What to do
Open the rejection details, compare the content with template-review and policy rules, then edit or appeal with samples.
132012 Template variable format mismatch
What actually causes it
A parameter value does not match the component type or format declared by the approved template.
What to do
Match every runtime parameter to the template's required type and position.
132015 Template paused for low quality
What actually causes it
Negative user feedback reduced template quality enough for Meta to pause sends.
What to do
Improve the content and wait until the edited template is approved and active.
132016 Template permanently disabled
What actually causes it
The template was paused repeatedly for low quality and can no longer be reactivated.
What to do
Create a materially improved new template rather than resending the disabled one.
132068 Flow blocked
What actually causes it
The Flow referenced by the template is in a blocked state.
What to do
Fix the Flow's reported issue and return it to an eligible state.
132069 Flow throttled
What actually causes it
A throttled Flow already sent 10 messages in the preceding hour.
What to do
Correct the Flow issue and wait for the hourly throttle window to clear.
133000 Previous deregistration failed
What actually causes it
The number has an unresolved failed deregistration attempt.
What to do
Deregister the number successfully before attempting registration.
133004 Registration server unavailable
What actually causes it
Meta's registration service is temporarily unavailable.
What to do
Check platform status and response details, then retry later.
133005 Incorrect two-step PIN
What actually causes it
The six-digit PIN does not match the number's two-step verification setting.
What to do
Use the correct PIN or reset two-step verification and set a new one.
133006 Number not verified
What actually causes it
Registration was attempted before phone ownership verification completed.
What to do
Verify ownership of the number, then register it.
133008 Too many PIN guesses
What actually causes it
Repeated incorrect two-step PIN attempts triggered a temporary limit.
What to do
Wait for the duration given in the response details before trying again.
133009 PIN entered too quickly
What actually causes it
Two-step PIN attempts were submitted faster than Meta permits.
What to do
Wait for the interval specified in response details.
133010 Phone number not registered
What actually causes it
The number has not been registered on the WhatsApp Business Platform, even if it exists in Business Manager.
What to do
Complete the platform registration call before using the number.
133015 Recent deletion still processing
What actually causes it
The phone number was deleted recently and Meta has not completed deletion.
What to do
Wait at least five minutes, then retry.
134011 WhatsApp Payments terms pending
What actually causes it
The WABA has not accepted the WhatsApp Payments terms required for this operation.
What to do
Use the link in the error to accept the terms before retrying.
135000 Unknown request-parameter error
What actually causes it
The request parameters fail validation, but Meta did not identify the exact parameter in the code title.
What to do
Validate request syntax against the endpoint reference and contact support if the response details do not resolve it.
Marketing Messages API
Errors specific to Meta's separate Marketing Messages API for WhatsApp.
100 Invalid parameter: message must be a template
What actually causes it
The Marketing Messages API received a non-template payload.
What to do
Send a marketing template message instead.
131009 Invalid parameter value
What actually causes it
A parameter is unsupported, or a newly connected ad has not finished synchronizing.
What to do
Validate the parameter; if ad sync is involved, wait 10 minutes before retrying.
131055 Method not allowed
What actually causes it
The request contains a free-form message or a utility or authentication template.
What to do
Use a template categorized as marketing.
134100 Only marketing messages supported
What actually causes it
A utility or authentication template was submitted to a marketing-only endpoint.
What to do
Send only a MARKETING template through this API.
134101 Template still synchronizing
What actually causes it
A newly created template has not completed ad synchronization, which can take up to 10 minutes.
What to do
Wait 10 minutes, then retry the same approved marketing template.
134102 Template unavailable
What actually causes it
Template ad synchronization failed or the WABA is not eligible and onboarded for the Marketing Messages API.
What to do
Check marketing_messages_lite_api_status; if it is ONBOARDED and the error continues, contact Meta support.
132018 Template validation error
What actually causes it
The runtime parameters do not satisfy the selected template's configuration.
What to do
Use the returned validation details to correct the parameters and resend.
1752041 Duplicate onboarding request
What actually causes it
Another partner already invited this business customer to onboard; only the first partner request is accepted.
What to do
Do not submit another request. Eligible WABAs are included in the existing onboarding process.
No matching code
Try a shorter code, a symptom such as “media”, or switch back to all groups.
DIAGNOSIS ORDER
The title is not the root cause
Read error.code first, then error_data.details.
Meta says the details field is the place most likely to identify the bad
parameter, accepted value, or underlying condition. Titles are being
deprecated, and error_subcode is already deprecated for
Graph API v16.0 and later.
- Capture both the synchronous Graph API response and asynchronous
messageswebhook failures. - Branch on
code, then usedetailsto distinguish bucket errors such as 131026. - Keep
fbtrace_idfor Meta support, but redact tokens, phone numbers and message content from ordinary logs. - Retry only temporary failures. Policy blocks, opt-outs, invalid payloads and permanent template disablement need a state or content change.
TEMPLATE REJECTIONS
Every rejection reason Meta exposes
The status webhook's reason is a broad classification. For
INVALID_FORMAT, newer payloads can also include
rejection_info.reason and a specific recommendation.
ABUSIVE_CONTENT Meta found policy-violating content.
Inspect: Threats, harassment, pressure, prohibited commerce or requests for sensitive identifiers.
CATEGORY_NOT_AVAILABLE Deprecated An authentication template targeted a region where that category was unavailable.
Inspect: Legacy regional eligibility. Meta marks this reason as deprecated.
INCORRECT_CATEGORY The submitted category does not match what the message actually does.
Inspect: Promotional language inside utility content, or a non-authentication purpose submitted as authentication.
INVALID_FORMAT The template structure or variables are invalid.
Inspect: Braces, variable order, adjacent variables, dangling variables, component limits and component-specific formats.
NONE No rejection reason; Meta uses this value for events such as a pause.
Inspect: Read the webhook event and other_info instead of treating NONE as a rejection.
PROMOTIONAL Meta found policy-violating promotional content.
Inspect: The policy details and whether the content or category attempts to bypass marketing rules.
SCAM Meta found content resembling a scam or otherwise violating policy.
Inspect: Misleading claims, impersonation, deceptive urgency, suspicious payment requests or prohibited offers.
TAG_CONTENT_MISMATCH The template content does not match the category tag chosen at creation.
Inspect: The real purpose of the full message, including header, body, footer and buttons.
Important:
NONE is part of the documented
reason value set, but it is not a rejection. Check the webhook's
event before routing a template into a rejection workflow.
PRE-SUBMISSION CHECK
Every concrete rejection trigger in Meta's review guide
Malformed variables
Cause: Positional variables are missing braces or use mismatched braces instead of the {{1}} form.
Fix: Correct every opening and closing brace before resubmitting.
Special characters inside variables
Cause: A variable token itself contains characters such as #, $ or %.
Fix: Keep the placeholder token numeric and put punctuation in fixed text outside it.
Non-sequential variables
Cause: Positional variables skip or scramble numbers, such as {{1}}, {{2}}, {{5}}, {{4}}.
Fix: Number placeholders once, in ascending order, without gaps.
Too many variables for the message
Cause: There is too little fixed text to explain what each variable represents.
Fix: Remove variables or add descriptive fixed wording around them.
Dangling parameter
Cause: The message begins or ends with a variable.
Fix: Add meaningful fixed text before and after the variable.
Commerce Policy violation
Cause: The template's offer, description, price, fee, tax, disclosure or related media concerns a transaction that does not comply with WhatsApp's Commerce Policy.
Fix: Remove the prohibited transaction or make the entire offer and disclosure compliant—not only the body text.
Business Policy violation
Cause: The message asks for full payment-card or financial-account numbers, national identifiers, other sensitive identifiers, or documents that can expose them.
Fix: Do not collect sensitive identifiers in WhatsApp; partial identifiers can be used only where policy permits them.
Abusive or threatening content
Cause: The message threatens legal action, public shaming or another abusive consequence.
Fix: Remove coercive language and use a neutral, factual service message.
Component or emoji limit
Cause: A component exceeds the character or emoji allowance for that template format and tag.
Fix: Use the component-specific limit returned by Meta and shorten the content.
Duplicate template
Cause: The body and footer repeat the wording of an existing template. Meta does not apply this duplicate check to authentication templates.
Fix: Reuse the existing template or make the new body or footer genuinely distinct.
Last updated