Guides

WhatsApp Status

Reference guide for outbound message tracking: status flow, failure causes, and recommended actions

Status for Outbound Messages

Outbound messages follow a common sequence of status values:

StatusDescription
QUEUE

Messangi has received your request to create the message.

Indicates that the message has been scheduled for sending but has not yet been sent out. This status means the message is waiting in line to be processed and delivered to the recipient. It's essentially in a holding pattern, queued up in our system until it can be dispatched.

DEQUEUEDMessangi indicates that the message has been removed from the queue and is now being processed for sending. This transition occurs after the message was previously in a waiting state (queued) and is now actively being sent to META.
CODE_NOT_ALLOWED

Messangi suggests that the sender used is either not activated on the platform or lacks the capability to message the recipient. Additionally, it could be because the owner does not have a sender (WhatsApp mobile number) assigned, which is required to send the message.

Contact our support team to verify the Sender.

INCOMPLETE

Messangi indicates that a personalized WhatsApp message was sent without the necessary placeholder data filled in.

Please note, personalized messages are those that feature dynamic fields—like "Name", "Phone Number", "Last Name", and similar—which need to be populated before sending.

BLACKLISTED

Messangi indicates that the intended recipient's phone number is on a blocklist, preventing any messages from being sent to that number.

When a number is blocklisted, it is essentially blocked from receiving any further communications from the sender's number, ensuring that no messages are delivered to that recipient.

QUOTA_EXCEEDEDThe WhatsApp Business Account (WABA) has surpassed the allowed limit for sending messages within a specified period, as defined by WhatsApp's messaging policies or limits.
SENTIndicates that the message has been successfully dispatched from our system and is en route to META. This status means that the message is on its way to the recipient, but does not confirm that the message has been delivered to the end user. It signifies a successful handoff to the next stage in the message delivery process.
  • NOTE*: A message may remain in the "SENT" status despite being delivered. This is often because the recipient has disabled "Read receipts" in their WhatsApp settings (commonly known as the "blue double check").
In some instances, a message might stay in the "SENT" status without being delivered. Possible reasons for this are:

  1. Recipient Device Connectivity: Ensure that the recipient's device is connected to the internet. If the device is offline, powered off, or in an area with no coverage, the message will stay in the "SENT" status until it can be delivered or eventually discarded. Additionally, check that the recipient's phone number is registered and active on WhatsApp.

  2. Restrictions on the Recipient (Blocking or Privacy Settings): If the recipient has blocked the sender's number, the message may not be delivered, even if it shows as "SENT." Privacy settings on the recipient's device may also impact message delivery. The message might also not be delivered if the recipient hasn't accepted WhatsApp's latest Terms of Service and Privacy Policy or if they are using an outdated version of WhatsApp. WhatsApp recommends the following minimum versions:

    • Android: 2.21.15.15
    • SMBA: 2.21.15.15
    • iOS: 2.21.170.4
    • SMBI: 2.21.170.4
    • KaiOS: 2.2130.10
    • Web: 2.2132.6

  3. Restrictions for Authentication Templates: Authentication templates have security measures for linked devices, so authentication messages are sent only to the user's main WhatsApp device. For instance, if a user is on WhatsApp Web, OTP (One-Time Password) messages won't appear there and will only be visible on their main mobile app. WhatsApp tries to deliver these messages within their valid period, with a maximum retry time of 10 minutes. If delivery fails within this time, WhatsApp stops retrying, and the message may remain in the "SENT" status.

Status for Completed Messages

Once the message is sent, three final statuses are possible:

StatusDescription
DELIVRD

Messangi has received confirmation of message delivery from META.

The message has successfully reached the recipient's device. This status confirms that the message was not only sent and processed by META but also received by the intended recipient's WhatsApp application, ensuring that the communication was completed.

READIndicates that the recipient has opened and seen the message.
FAILED

Indicates that META could not deliver the message to the recipient's device.

Possible Reasons for WhatsApp "FAILED" status:

  • Network issues: This could include an unstable internet connection on the sender's or recipient's end, or issues with the WhatsApp servers.

  • Incorrect phone number: If the recipient's phone number is incorrect or not registered on WhatsApp, the message will fail to send.

  • Blocked contact: If the recipient has blocked the sender's number, the message will not be delivered.

  • Content restrictions: WhatsApp has restrictions on the type of content that can be sent through the platform. If a message contains content that violates these restrictions, it will be blocked.- 24-hour rule: If a user hasn't interacted with a business in the past 24 hours, non-template messages from that business will be marked as spam and won't be delivered.

FAILED status — Causes and recommended actions

When WhatsApp returns a FAILED status, it includes an error message identifying the cause. The table below describes each error, its meaning, and the recommended action.

Error / CodeDescriptionCommon causeRecommended action
Message undeliverableMessage not deliverableThe number has no active WhatsApp, is invalid, or the user has blocked the business.Validate and clean the number database before resending.
Healthy ecosystem engagementBlocked by Meta quality controlWhatsApp stopped sending to protect the ecosystem: low sender account quality, excessive blocks or user reports, or poor audience targeting.Improve database quality, reduce sending frequency, and monitor the sender number's quality rating.
User's number is part of an experimentNumber in a Meta experimentThe recipient's number is part of an internal WhatsApp test; a temporary condition on Meta's side.Retry later; the condition usually resolves on its own.
Media upload 502, DNS query shed at inflight capMedia upload error (502 – DNS)WhatsApp attempted to download the file and received a 502 error: the server or CDN did not respond in time.Check the availability and capacity of the server or CDN hosting the files.
Media upload 500, Internal Server ErrorMedia upload error (500 – Internal Server Error)The server hosting the media returned an internal 500 error when attempting to download the file.Review the media file host.
Recipient stopped marketing messagesVoluntary marketing opt-outThe recipient chose to stop receiving marketing messages from the business on WhatsApp.Respect the opt-out and permanently exclude the user from all promotional campaigns.
Media upload 500, Timed out waiting for sessionMedia upload error (500 – Session timeout)The media download timed out without an available session being established.Review the response times of the media server.
Media upload 500, Non retryable, UserErrorMedia upload error (500 – Non-retryable, client error)Internal 500 error classified as a client-side problem; the failure originates in the link or the source file.Fix or replace the media URL before any retry attempt.
Media upload 502, Non retryable, UserErrorMedia upload error (502 – Non-retryable, client error)502 error attributed to the client; the media server did not respond correctly.Fix the file source before resending.
Media upload 500, Timed out, Non retryable, UserErrorMedia upload error (500 – Timeout, non-retryable)Timeout (500) classified as a client error; not retryable without a fix.Review and correct the file source.
Media upload 502, DNS resolution timed outMedia upload error (502 – DNS timeout)The DNS for the media link could not be resolved within the allowed time.Verify the domain and DNS configuration of the server hosting the files.
Media upload 500, RST_STREAM from peerMedia upload error (500 – Connection interrupted)The connection to the media server was interrupted during download (RST_STREAM).Review the stability of the server or CDN delivering the files.
(blank)Failure with no cause detailWhatsApp did not return a specific reason for the failure.Monitor volume and escalate with the provider if it increases.
An unexpected error has occurred. Please retryUnexpected error – retryTemporary WhatsApp system condition or server saturation.Apply automatic retries. If it persists at high volume, escalate with Meta.
(#131000) Something went wrongCode 131000 – Generic system errorGeneric Meta system error with no specific cause exposed.Retry. If it persists, escalate with Meta support.
(#131009) Parameter value is not validCode 131009 – Invalid parameterA message parameter has an invalid value: incorrect format in a variable or template component.Review the message structure and the variables sent in the request.

Additional final statuses

In addition to FAILED, these two statuses prevent delivery before the message reaches META.

StatusDescriptionCommon causeRecommended action
INCOMPLETETemplate could not be retrievedThe template does not exist, is not approved, or the name/language does not match.Verify the template name, language, and approval status in Meta Business Manager.
BLACKLISTEDNumber on blocklistThe number was excluded from sends due to a previous opt-out, complaint, or compliance rule. Delivery was not attempted.Keep it excluded. Only re-add if new and verified consent exists.






Updated 6 days ago