Messages won't send? Three layers for systematically troubleshooting instant messaging message send failures

When troubleshooting instant messaging message send failures, the first step is not to check the network, but to confirm the failure pattern. There are usually only two types of send failures:Immediate error—the API call immediately returns an error code, timeout, or exception;False success—the message appears sent locally, but the recipient does not receive it or receives it much later. For the former, check client-side status and the connection layer first; for the latter, the problem is most likely in server-side storage, routing, or policy.

Below, proceed through the three layers: client side—connection layer—server side.

First, use the two symptoms to identify the faulty layer: immediate error vs. false success.

• Immediate errors:The send request immediately returns 401, 403, 413, or a network timeout. Check SDK initialization status, Token permissions, and message body limits first.
• False success:The message is sent successfully on this end, but other endpoints do not receive it. Check server-side offline message storage, queue backlog, and policy hits first.

Layer one: Client-side send failures — SDK initialization, Token, and message format

A send action can fail before it even leaves the device, and most failures are configuration issues rather than network issues. Check the following items one by one:

• If you call the send API before SDK initialization completes or before the init callback returns success, you will get an error such as "uninitialized" or -1.
• Token expired or insufficient permissions. When 401/403 is returned, check the server-side token validity period and current user permissions first; do not rush to change network settings.
• Message body exceeds the limit. When text length, image size, or custom fields exceed server-side limits, common return codes are 413 or 400.
• Custom message format mismatch. If extended field types do not match the protocol definition, serialization will fail.
• Local network interception. Enterprise firewalls or security software may block requests to the message gateway. You can use a minimal request to reproduce and determine this.

Layer Two: Connection-layer "false online" — long-lived connection disconnection, heartbeat, and reconnection

An online status in the UI does not mean the persistent connection is actually usable. Many "send failures" happen because the connection is half-open or has been silently disconnected, and the sender keeps writing data to a dead connection.

• The heartbeat interval is inappropriate. The server has already determined that the connection timed out and reclaimed it, while the client still shows online.
• No reconnection after a network switch. When switching from Wi-Fi to cellular data, the old connection is not released in time, and new send requests are left hanging.
• The App is killed by the system while in the background. After the persistent connection is dropped, it is not re-established, and the old status is still shown when returning to the foreground.
• TLS certificate verification fails. In private deployment environments using self-signed certificates, the client may silently disconnect.

The criterion is not the status shown at the top of the App, but whether packet capture confirms there are still heartbeat uplinks, or whether the client reconnect logs contain reconnect failures.

Layer three: Server-side policies and storage — messages dropped, restricted, or blocked by risk control.

If a message reaches the server but the recipient does not receive it, it usually does not mean the message never entered the system; rather, it was blocked by storage policies, routing rules, or risk control logic.

• Offline messages were not stored or failed to be stored. When the recipient comes online, history cannot be pulled. Refer toCommon Causes and Fixes for Not Receiving Offline Messages.
• Message queue backlog. The server has already received the messages but the delivery thread cannot process them in time, manifesting as delay rather than immediate failure.
• Rate limit triggered. When the same user sends a large volume in a short time, messages are silently dropped after rate limiting is triggered.
• Sensitive words or risk control policies falsely block messages. When a policy is matched, no error is returned and the message is not delivered.
• Multi-device sync overwrites. New messages are overwritten by sync actions from older messages, causing some devices to show "sent" but with missing content.

When handling this, first check the message status, queue depth, and policy hit records in server-side logs; do not focus only on client error codes.