What is error 131047 on WhatsApp API?
WhatsApp Cloud API errors fall into template mismatches, session window violations, opt-out blocks, rate limits, and policy rejections — log the full webhook payload, fix root cause, and never blindly retry 4xx policy errors. Re-engagement message required — outside the 24-hour session window. Send an approved Utility or Marketing template; resume free-form after customer reply.
Last updated: 24 June 2026
Quick answer: WhatsApp Cloud API errors fall into five buckets: template issues, session window violations, opt-out blocks, rate limits, and policy rejections. Always log the full error code + subcode from the webhook payload, cross-reference Meta's error reference, fix the root cause — and never blindly retry 4xx policy errors, which waste API quota and can trigger quality penalties.
Developers integrating via raw Graph API or CPaaS wrappers like Twilio spend disproportionate time parsing opaque error payloads. The same ten codes account for 90%+ of production failures. This guide maps each to root cause, fix, and retry strategy.
Common error codes reference
| Code | Name | Root cause | Fix | Retry? |
|---|---|---|---|---|
| 131026 | Message undeliverable | Invalid phone, not on WhatsApp, or user blocked business | Validate E.164 format; remove from list | No |
| 131047 | Re-engagement required | Outside 24-hour session window | Send approved Utility or Marketing template | No — fix approach |
| 130472 | User opted out | Contact unsubscribed from Marketing | Remove from Marketing list; sync opt-out to CRM | No |
| 132000 | Template param mismatch | Variable count, order, or format wrong | Match exact variable count and types from approval | Yes after fix |
| 132001 | Template does not exist | Wrong template name or language code | Verify name + language match approved template | Yes after fix |
| 132005 | Template hydrated text too long | Variable values exceed character limit | Truncate or shorten variable content | Yes after fix |
| 80007 | Rate limit hit | Exceeded throughput tier or burst limit | Exponential backoff; request tier upgrade | Yes with backoff |
| 131031 | Business account locked | Policy violation or quality rating critical | Stop sends; appeal via Meta Business Support | No |
| 368 | Temporarily blocked | Policy violation — spam pattern detected | Pause Marketing; audit list and content | No |
| 100 | Invalid parameter | Malformed request body or missing field | Validate JSON against API spec | Yes after fix |
Webhook delivery status debugging
Sent ≠ delivered. Track the full message lifecycle via webhooks:
| Status | Meaning | Next step |
|---|---|---|
| sent | Meta accepted the API request | Wait for delivered or failed webhook |
| delivered | Reached user's device | Success — no action needed |
| read | User opened the message | Success — engagement tracked |
| failed | Delivery failed | Log error code; apply fix from table above |
Step-by-step debugging checklist
- Capture full payload — error code, subcode, wamid, recipient phone, timestamp
- Verify template — name, language, variable count and order match Meta-approved version exactly
- Confirm phone format — E.164 with country code (e.g. +919876543210, no spaces or dashes)
- Check session window — error 131047 means template required, not free-form retry
- Check opt-out status — error 130472 means remove from Marketing list permanently
- Review quality rating — low rating throttles throughput; error 80007 may be tier-related
- Test single message — never batch-retry failures; fix one, verify, then scale
- Check WABA status — error 131031 means account-level restriction; stop all sends
Template-specific failures
| Symptom | Likely cause | Fix |
|---|---|---|
| 132000 param mismatch | Sent 3 variables, template expects 2 | Count {{1}}, {{2}} placeholders in approved body |
| Header image fails | URL not publicly accessible or wrong aspect ratio | Use HTTPS URL; 1.91:1 for image headers |
| Button URL invalid | Dynamic URL variable malformed | Ensure full https:// URL in variable |
| Template paused | Low quality rating on this template | Pause campaign; revise copy; resubmit for approval |
Template workflow: Template approval guide
Rate limits and throughput tiers
Meta assigns messaging throughput tiers based on quality rating and business verification:
- Tier 1: 1,000 business-initiated conversations / 24h
- Tier 2: 10,000 / 24h
- Tier 3: 100,000 / 24h
- Tier 4: Unlimited (with maintained quality)
Hit error 80007? Implement exponential backoff (1s, 2s, 4s, 8s). Request tier upgrade in Meta Business Manager after 30 days of green quality rating.
Platform vs DIY debugging
Raw Graph API and Twilio DIY setups require parsing nested JSON error objects and cross-referencing Meta docs. Ominiflow dashboard surfaces delivery failures with human-readable reasons, template mismatch hints, and session window indicators — reducing mean-time-to-resolution from hours to minutes for ops teams without dedicated API engineers.
See: 24-hour window · Ban prevention · CPaaS guide · Twilio vs Ominiflow · Pricing · Comparisons
FAQ
Why do messages show sent but not delivered? expand_more
Webhook delivery status lags behind sent status. Common causes: invalid number (131026), user blocked business, opted out (130472), or phone not registered on WhatsApp. Check failed webhook for specific code.
What is error 131047 on WhatsApp API? expand_more
Re-engagement message required — you are outside the 24-hour session window. Send an approved template; resume free-form after customer replies.
How do I debug WhatsApp webhook failures? expand_more
Log full error payload with wamid, verify template parameters and phone E.164 format, check rate limits and quality rating, test with single message before batch retry.
How do I increase rate limits? expand_more
Maintain green quality rating for 30+ days, complete business verification, and request tier upgrade in Meta Business Manager.
