Message Delivery Errors
Message Delivery related Error list in WhatsApp Business API solution
Message delivery errors occur when the API successfully receives a message request, but the message cannot be delivered to the recipient. These errors cover a wide range of scenarios including undeliverable recipients, expired conversation windows, media failures, and business eligibility issues.
These errors are typically returned either synchronously in the API response (HTTP 400) or asynchronously via the messages webhook. It is important to monitor both channels for complete error visibility.
____________________________________________________________________________________________
Error 131026 - Undeliverable
Message Undeliverable — Recipient Cannot Receive Message
ERROR CODE
131026
ERROR SUMMARY
Message Undeliverable — Recipient Cannot Receive Message
ERROR DESCRIPTION
The message could not be delivered to the recipient for one of several reasons: (1) the recipient phone number is not registered on WhatsApp, (2) the recipient has not accepted WhatsApp's current Terms of Service and Privacy Policy, or (3) the recipient is using an outdated WhatsApp client version that does not support the message type being sent.
Minimum supported WhatsApp versions for all message types: Android 2.21.15.15, iOS 2.21.170.4, WhatsApp Business for Android 2.21.15.15, WhatsApp Business for iOS 2.21.170.4, KaiOS 2.2130.10, Web 2.2132.6.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Before sending, verify that the recipient phone number is registered on WhatsApp. You can use the WhatsApp number lookup feature or implement a validation step in your data import flow.
2. If you receive this error consistently for a number, mark it as 'invalid WhatsApp number' in your CRM to avoid retrying.
3. For interactive message types (lists, buttons, flows), inform users they may need to update their WhatsApp app to the latest version to receive these messages.
4. Ask the user (via a non-WhatsApp channel) to verify they can send a message to your WhatsApp business number, which confirms their app is set up correctly.
5. If the issue is related to Terms of Service acceptance, the user will be prompted the next time they open WhatsApp.
OTHER NOTES
This is one of the most common permanent delivery failures. Implementing a phone number verification step in your contact import flow (using the contacts API or third-party WA number checker) significantly reduces this error.
Chakra Chat's contact import wizard includes an optional WhatsApp number validation step that checks validity before contacts are added to campaigns.
Error 131037 - 555 Display Name
555 Number Needs Display Name Approval
ERROR CODE
131037
ERROR SUMMARY
555 Number Needs Display Name Approval
ERROR DESCRIPTION
The 555 test/sandbox phone number being used to send the request does not have an approved display name. 555 numbers are special test numbers available during development and must have their display name approved before they can send messages.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Navigate to the WhatsApp Manager and find the 555 phone number.
2. Update or set the display name for the number.
3. Wait for Meta's display name approval, which typically takes 1–2 business days.
4. Alternatively, use a real business phone number that has already been verified and has an approved display name for testing.
OTHER NOTES
555 numbers are intended for development testing only. For production deployments, always use a properly registered and verified business phone number.
Error 131042 - Payment Issue
Business Eligibility Payment Issue
ERROR CODE
131042
ERROR SUMMARY
Business Eligibility Payment Issue
ERROR DESCRIPTION
There is an issue with the payment method or billing configuration associated with the WhatsApp Business Account. This prevents message sending. Common causes include: no payment account attached to the WABA, credit line over limit, credit line not set or not active, WABA deleted or suspended, timezone/currency not configured, or a pending/declined 'Messaging For' (On-Behalf-Of) request.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Review the full list of possible payment issues listed in the description and check each one systematically.
2. Verify that a payment account is attached to your WABA in Meta Business Suite → WhatsApp Manager → Settings.
3. Check that your credit line is active and not over its limit in the payment settings.
4. Ensure the WABA has its timezone and currency configured correctly.
5. If you are a Tech Provider managing on behalf of a client, check that the 'Messaging For' request has been accepted by the client.
6. Refer to the Meta Help Center article 'About Billing For Your WhatsApp Business Account' at https://www.facebook.com/business/help/2225184664363779.
OTHER NOTES
This error can cause widespread message failures if a billing issue goes undetected. Chakra Chat will surface payment-related WABA health alerts in the notifications panel.
Free-tier (WhatsApp Business App) numbers do not have credit line requirements, but Cloud API numbers always require a properly configured billing setup.
Error 131047 - Window Expired
Re-engagement Message - 24-Hour Window Expired
ERROR CODE
131047
ERROR SUMMARY
Re-engagement Message — 24-Hour Window Expired
ERROR DESCRIPTION
The business is attempting to send a free-form (non-template) message to a recipient, but more than 24 hours have elapsed since the recipient last sent a message to the business. WhatsApp's customer service window policy requires that free-form messages can only be sent within a 24-hour window following the last inbound message from the customer.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Send an approved template message instead of a free-form message. Template messages can be sent at any time regardless of the 24-hour window.
2. Use a re-engagement template designed to invite the user back into the conversation.
3. Review your automation flows in Chakra Chat to ensure they do not attempt to send free-form messages after the window has expired.
4. Implement window tracking in your chatbot logic — store the timestamp of the last inbound message and check it before sending a non-template message.
OTHER NOTES
The 24-hour service window is a core WhatsApp policy designed to protect users. Businesses can only send unlimited free-form messages during an active conversation window.
Chakra Chat tracks conversation window status per contact and will warn agents in the inbox when the window is close to expiring (typically 1 hour before).
Error 131049 — Meta Rejected
Meta Chose Not to Deliver — Per-User Marketing Limit
ERROR CODE
131049
ERROR SUMMARY
Meta Chose Not to Deliver — Per-User Marketing Limit
ERROR DESCRIPTION
Meta's system decided not to deliver this particular marketing template message in order to maintain a healthy messaging ecosystem. This is triggered by the per-user marketing template message limits, which cap how many marketing messages a single user can receive from all businesses combined within a given period.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Do not immediately retry sending this message. Retrying will result in the same error as the limit may remain in effect for a variable duration.
2. Wait at least 24 hours before attempting to resend the template message to this user.
3. Review the Per-User Marketing Template Message Limits documentation at https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits.
4. Consider sending at lower frequency to reduce the likelihood of hitting this limit.
OTHER NOTES
This limit is applied by Meta at the ecosystem level and cannot be bypassed. It is part of Meta's effort to prevent users from being overwhelmed by marketing messages from multiple businesses.
You will not know the exact limit or when it resets for a specific user — this is intentional to prevent gaming of the system.
Error 131050 — User Opted Out
User Has Stopped Receipt of Marketing Messages
ERROR CODE
131050
ERROR SUMMARY
User Has Stopped Receipt of Marketing Messages
ERROR DESCRIPTION
The recipient has explicitly opted out of receiving marketing template messages from your business on WhatsApp. WhatsApp introduced per-business marketing opt-outs that allow users to stop marketing messages from a specific business without having to block them entirely.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Do not retry sending marketing messages to this user. Their opt-out preference must be respected.
2. Update your contact database to mark this user as opted out of WhatsApp marketing.
3. Subscribe to the 'user_preferences' webhook to receive real-time notifications when users opt in or out of marketing messages. See https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/user_preferences.
4. You can still send utility or authentication template messages to this user — the opt-out only applies to marketing category templates.
OTHER NOTES
Respecting opt-outs is both a legal requirement (in many jurisdictions) and a WhatsApp policy requirement. Attempting to circumvent opt-outs (e.g., by miscategorising templates) is a policy violation.
Chakra Chat automatically syncs user_preferences webhook data to contact opt-out status. Opted-out contacts will be excluded from future marketing campaigns.
Error 131051 — Unsupported Type
Unsupported Message Type
ERROR CODE
131051
ERROR SUMMARY
Unsupported Message Type
ERROR DESCRIPTION
The message type specified in the API request is not supported by the WhatsApp Cloud API, or the recipient's device/version does not support the specified message type.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Review the supported message types in the WhatsApp Messages documentation at https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#message-types.
2. Ensure the 'type' field in your message object is set to a valid, supported value.
3. If sending interactive message types (lists, buttons, flows), confirm the recipient is using a sufficiently recent WhatsApp version.
4. Fallback to a text-based message if the interactive type is not supported.
OTHER NOTES
The supported message types include: text, image, audio, video, document, sticker, location, contacts, interactive, template, and reaction. Sending any other type will result in this error.
Error 131052 - Media Error
Media Download Error — Unable to Download User-Sent Media
ERROR CODE
131052
ERROR SUMMARY
Media Download Error — Unable to Download User-Sent Media
ERROR DESCRIPTION
The WhatsApp platform was unable to download a media file that the user sent to the business. This may indicate a corrupted media file, an unsupported media format, or a temporary issue on WhatsApp's media servers.
This error appears in the messages webhook when processing incoming messages, not when sending outbound messages.
RESOLUTION & TROUBLESHOOTING STEPS
1. Check the 'error.error_data.details' field in the messages webhook payload for more specific information.
2. Ask the user (via a text reply) to resend the media file.
3. If the error persists for a specific file, ask the user to try sending the file using a different method (e.g., share as a document instead of an image).
4. Ensure your webhook endpoint is correctly configured to receive and acknowledge media message events.
OTHER NOTES
Media files sent by users are stored temporarily on WhatsApp's servers and must be downloaded within a limited time window (typically 30 days) before they expire.
Chakra Chat's inbox automatically attempts to download and cache user-sent media. If a download fails, the agent will see an error indicator in the conversation thread.
Error 131053 - Media Upload Error
Media Upload Error - Unable to Upload Business-Sent Media
ERROR CODE
131053
ERROR SUMMARY
Media Upload Error — Unable to Upload Business-Sent Media
ERROR DESCRIPTION
The WhatsApp platform was unable to upload the media file included in an outbound message. This may be due to an unsupported media type, a file that exceeds size limits, a corrupted file, or a temporary server issue.
HTTP Status: 400 Bad Request. More detail is available in the 'error.error_data.details' field of the webhook notification.
RESOLUTION & TROUBLESHOOTING STEPS
1. Verify that the media file type is in the supported formats list at https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media#supported-media-types.
2. Check the file size limits: Images — 5MB; Videos — 16MB; Audio — 16MB; Documents — 100MB.
3. Use the UNIX file inspection command to verify the actual MIME type: 'file -I filename.ext'. Ensure it matches the declared type.
4. Re-upload the media using the WhatsApp Media API before sending, and use the returned media ID in the message.
5. If the error persists with a valid file, check the WhatsApp Platform Status page for any active media service outages.
OTHER NOTES
Using the Media API to pre-upload files (rather than hosting them on an external URL) is more reliable and results in faster delivery. Chakra Chat's media manager uses this approach by default.
When using URL-based media, ensure the URL is publicly accessible, returns the correct Content-Type header, and does not require authentication.
Error 131021 - Same Number
Recipient Cannot Be Sender — Same Number Error
ERROR CODE
131021
ERROR SUMMARY
Recipient Cannot Be Sender — Same Number Error
ERROR DESCRIPTION
The phone number specified as the recipient is the same as the sender (business) phone number. WhatsApp does not allow a business to send a message to itself.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Verify that the 'to' field in the API request contains the recipient's phone number, not the business number.
2. Check your integration logic for any bugs that may result in the sender number being used as the recipient.
3. This error often appears during development when testing with your own number — ensure test recipient numbers are different from the configured sender number.
OTHER NOTES
This is typically a development/integration error rather than a production issue. Automated tests should include a check that the sender and recipient numbers are different.
Error 131057 - Maintenance
Account in Maintenance Mode
ERROR CODE
131057
ERROR SUMMARY
Account in Maintenance Mode
ERROR DESCRIPTION
The WhatsApp Business Account is currently in maintenance mode and cannot send or receive messages. This may occur when the account is undergoing a throughput upgrade or other backend maintenance.
HTTP Status: 500 Internal Server Error (Bad Request).
RESOLUTION & TROUBLESHOOTING STEPS
1. Wait for the maintenance window to complete. Maintenance mode is typically temporary (minutes to a few hours).
2. Implement retry logic with exponential backoff to automatically resume sending once the account exits maintenance mode.
3. Monitor the WhatsApp Platform Status page (https://metastatus.com/whatsapp-business-api) for any reported maintenance windows.
4. Check the Health Status API for more information about the current account state.
OTHER NOTES
If you have requested a throughput upgrade, expect a brief maintenance window during which messages may fail. Schedule throughput upgrades during low-traffic periods.
Error 135000 — Generic User Error
Generic User Error — Unknown Request Parameter Error
ERROR CODE
135000
ERROR SUMMARY
Generic User Error — Unknown Request Parameter Error
ERROR DESCRIPTION
A generic catch-all error indicating that the message failed due to an unknown error with the request parameters. This error is returned when the system cannot classify the failure into a more specific error code.
HTTP Status: 400 Bad Request.
RESOLUTION & TROUBLESHOOTING STEPS
1. Review the API endpoint reference documentation to verify your request syntax and parameters.
2. Double-check all required fields are present and correctly formatted.
3. Try reproducing the error with a minimal test request to isolate the parameter causing the issue.
4. If the error persists across multiple valid requests, contact Meta Customer Support and include the 'fbtrace_id' from the error response for investigation.
OTHER NOTES
Because Error 135000 is a catch-all, the 'details' field in the error response is the most important diagnostic tool. Always log the full error response, not just the code.