Description
What is error 131049?
Error 131049 (Per-User Marketing Limit) is the failure Meta reports when it does not deliver a marketing template message “to maintain healthy ecosystem engagement”. WhatsApp caps how many marketing templates an individual user receives from all businesses over a period, based on how that user engages with marketing. Once a person has reached the cap, further marketing templates to them are withheld, whichever business sends them and however well targeted the message is.
The error normally arrives in a statuses webhook: the send call returns a WAMID, then that WAMID is reported failed with code: 131049. Meta does not publish the cap, which varies from user to user, and the limits are not active for users in the EEA, the UK, Japan or South Korea. Marketing messages sent while a 24-hour customer service window is open (a promotion sent while the customer is chatting with you) do not count towards the limit, and utility and authentication templates are not subject to it.
131049 says nothing bad about the number. Error 131026 (Message Undeliverable) means the recipient can't be reached; with 131049 the person is on WhatsApp and may receive your marketing on another day. Meta advises against retrying straight away and suggests waiting at least 24 hours. Paying more doesn't bypass it either: a higher max price on the Marketing Messages API for WhatsApp (formerly MM Lite) does not override per-user limits.
Key takeaways
- Error 131049 means Meta chose not to deliver a marketing template because the recipient reached WhatsApp's per-user marketing limit.
- The limit counts marketing templates a person receives from all businesses and depends on that person's engagement.
- Retrying immediately won't help: wait at least 24 hours, then retry once or twice at most.
- Withheld messages aren't delivered, so they aren't billed; report them apart from genuine delivery failures.
- Marketing sent inside an open customer service window doesn't count towards the limit.
Properties
Error 131049: key facts and limits
- Code
- 131049
- Meta's wording
- Not delivered to maintain healthy ecosystem engagement
- Applies to
- Marketing templates only
- Doesn't count
- Marketing sent inside an open service window
- Not active in
- EEA, UK, Japan, South Korea
- Retry guidance
- Wait at least 24 hours
- Billing
- Not delivered, not charged
Mechanics
How does error 131049 work?
step 1 — You send a marketing template
The API accepts the request and returns a WAMID, exactly as for any other send.
step 2 — Meta checks the recipient's allowance
If the person has already received their share of marketing templates from businesses, Meta withholds yours.
step 3 — A failed status arrives with 131049
The webhook marks the WAMID failed, and its webhook error objects carry code 131049. Nothing was delivered, so it isn't a billable message.
step 4 — Schedule at most a delayed retry
Wait at least 24 hours before resending, cap retries at one or two, and drop the message if the offer will have expired.
step 5 — Report it separately
Count 131049 as “withheld by per-user limit” in campaign reports, distinct from undeliverable numbers and other failures, and watch its share per segment.
Usage
Error 131049 in code
const DAY = 24 * 60 * 60 * 1000;const MAX_RETRIES = 2;async function onFailedStatus(status, job) {const code = status.errors?.[0]?.code;if (code !== 131049) return handleOtherFailure(status, job);metrics.increment("whatsapp.withheld_per_user_limit", { campaign: job.campaignId });const attempt = (job.attempt ?? 0) + 1;const retryAt = Date.now() + DAY * 2 ** (attempt - 1); // 24 h, then 48 hif (attempt > MAX_RETRIES || retryAt > job.offerEndsAt) {return markOutcome(job, "withheld_not_retried");}await queue.add("send-template", { ...job, attempt }, { delay: retryAt - Date.now() });}
Never sooner than 24 hours, never more than twice, never after the offer ends.
Why it matters
Why does error 131049 matter?
Marketers read 131049 as lost reach, and it is the most often misreported error: lumped in with “failed”, it looks like a list or platform problem; retried in a loop, it wastes API calls and helps no one. Reported as its own outcome, “withheld by per-user limit”, it tells a useful story: the audience is saturated by marketing from many businesses, so sharper targeting, better timing and messages that start conversations will do more than resending.
Caveats
Common mistakes with error 131049
Retrying instantly
The limit won't have reset minutes later, so instant retries fail again and add noise. Park the message and retry no sooner than 24 hours.
Reporting it as undeliverable
Merging 131049 with 131026 makes reachable customers look dead and can get them wrongly suppressed. Keep the outcomes separate.
Expecting a higher price to fix it
Max price changes what Meta may charge per delivered marketing message; it doesn't lift per-user limits. Messages a person won't receive at any price stay withheld.
Re-sending promotions as utility templates
Dressing marketing up as utility breaks category rules, and Meta recategorises templates whose content is promotional. Fix targeting, not the label.
Retrying an offer that has expired
A retry two days later that promotes a sale that ended yesterday hurts engagement. Tie every retry to the offer's end time.
Example
Example: A weekend sale in Bengaluru
A Bengaluru fashion label sends a Friday-evening sale template to 25,000 opted-in customers, and about 7% come back failed with 131049. The old pipeline retried each failure three times within ten minutes, and every retry failed again. Now 131049 failures are parked and retried once on Saturday evening, 24 hours later; in this campaign roughly a third of them were delivered, and the rest were dropped when the sale ended on Sunday. The weekly report shows “withheld by per-user limit” as its own line, which led the team to move part of its promotions into replies to customers who had just messaged them.
Notes
Best practices for error 131049
- Send promotions to customers who have just messaged you: inside an open window they don't count towards the limit.
- Segment by engagement and send fewer, better-targeted campaigns to people who rarely respond.
- Track the 131049 share per segment over time; a rising share means that audience is saturated.
- Exclude 131049 failures from deliverability alerts that are meant to catch broken numbers or outages.
Questions
Error 131049 (Per-User Marketing Limit) FAQs
- What does “not delivered to maintain healthy ecosystem engagement” mean?
- It is error 131049: Meta withheld your marketing template because the recipient had reached WhatsApp's per-user marketing limit, which counts marketing from all businesses.
- How long should I wait before retrying a 131049 failure?
- At least 24 hours. Immediate retries hit the same limit; one or two retries, a day or more apart and within the offer's validity, is a sensible maximum.
- Am I charged for messages that fail with 131049?
- No. The message was not delivered, and Meta bills delivered messages only, so a withheld marketing template costs nothing.
- Does error 131049 affect utility or OTP messages?
- No. Per-user limits cover marketing templates. Utility and authentication templates aren't withheld under them, provided their content genuinely belongs in those categories.
- Can I see a customer's marketing limit?
- No. Meta doesn't publish the cap, and it varies from user to user based on engagement. You only learn that a message was withheld from the 131049 status.