Reason Code

Reference every current protocol reason value 0–29 with name, phase, retry guidance, and reachability.

Goal and completion criteria

This page maps the complete current pkg/protocol/frame.ReasonCode enum to developer decisions. When finished, you should preserve the raw value, interpret it in a CONNACK, SENDACK, or other phase, and apply bounded retries that do not amplify failure.

Compatibility target

The table is generated from the authoritative Go enum and shared metadata, and CI verifies values 0–29 and their names. It is tied to the current API compatibility snapshot, with no separate handwritten copy in each MDX locale.

Complete WuKongIM wire ReasonCode enum
Value / name	Stage	Retry guidance	Reachability	Meaning
`0` `ReasonUnknown`	CONNECT / SEND	Application policy decides	Compatibility path	Unclassified or unknown result; retain context and avoid blind retries.
`1` `ReasonSuccess`	CONNECT / SEND	Not applicable	Active path	The request succeeded; the completion boundary depends on the packet type.
`2` `ReasonAuthFail`	CONNECT / SEND	Repair the request first	Active path	Authentication or sender identity was rejected; repair credentials or server policy first.
`3` `ReasonSubscriberNotExist`	SEND	Repair the request first	Active path	The sender is absent from the channel membership required for this send.
`4` `ReasonInBlacklist`	SEND	Repair the request first	Active path	The sender is present in the channel denylist.
`5` `ReasonChannelNotExist`	SEND	Application policy decides	Active path	The channel does not exist or cannot currently accept the send.
`6` `ReasonUserNotOnNode`	CONNECT / delivery	Refresh route; reuse idempotency key	Compatibility path	The target user is not on this node; refresh routing before deciding whether to retry.
`7` `ReasonSenderOffline`	SEND	Application policy decides	Reserved	Reserved sender-offline result; no current product path emits this value.
`8` `ReasonMsgKeyError`	SEND	Repair the request first	Reserved	Reserved message-key or integrity error; no current product path emits this value.
`9` `ReasonPayloadDecodeError`	SEND	Repair the request first	Active path	Malformed or unsupported SEND request (fields or payload), including decode failures.
`10` `ReasonForwardSendPacketError`	SEND	Retry with bounded backoff	Compatibility path	A compatibility forwarding path could not forward the send packet.
`11` `ReasonNotAllowSend`	SEND	Repair the request first	Active path	Channel policy does not allow this sender to send.
`12` `ReasonConnectKick`	CONNECT / disconnect	Application policy decides	Reserved	Reserved connection-kick result; no current product path emits this value.
`13` `ReasonNotInWhitelist`	SEND	Repair the request first	Active path	The channel requires an allowlist and the sender is absent from it.
`14` `ReasonQueryTokenError`	CONNECT	Retry with bounded backoff	Reserved	Reserved token-query error; the current default composition does not emit this value.
`15` `ReasonSystemError`	CONNECT / SEND	Retry with bounded backoff	Active path	Server pressure or internal error; retry with bounded backoff and the same idempotency key.
`16` `ReasonChannelIDError`	SEND	Repair the request first	Reserved	Reserved channel-identifier error; current product paths use other error mappings.
`17` `ReasonNodeMatchError`	CONNECT / SEND	Refresh route; reuse idempotency key	Compatibility path	Compatibility node matching failed; refresh routing.
`18` `ReasonNodeNotMatch`	SEND	Refresh route; reuse idempotency key	Active path	The current node is not the fresh authority target; refresh routing and reuse the original idempotency key.
`19` `ReasonBan`	CONNECT / SEND	Repair the request first	Active path	The user connection or channel send is banned.
`20` `ReasonNotSupportHeader`	CONNECT / SEND	Repair the request first	Reserved	Reserved unsupported-header result; no current product path emits this value.
`21` `ReasonClientKeyIsEmpty`	CONNECT	Repair the request first	Active path	A handshake that requires a client key did not provide one.
`22` `ReasonRateLimit`	CONNECT / SEND	Retry with bounded backoff	Compatibility path	Rate-limit result retained by clients and workload tooling; the current default product path does not emit it.
`23` `ReasonNotSupportChannelType`	SEND	Repair the request first	Reserved	Reserved unsupported-channel-type result; no current product path emits this value.
`24` `ReasonDisband`	SEND	Repair the request first	Active path	The channel is disbanded and cannot accept further sends.
`25` `ReasonSendBan`	SEND	Repair the request first	Active path	The sender is banned from sending.
`26` `ReasonChannelDeleting`	SEND	Retry with bounded backoff	Reserved	Reserved channel-deleting result; no current product path emits this value.
`27` `ReasonProtocolUpgradeRequired`	CONNECT	Upgrade the client first	Compatibility path	The gateway retains this connection-failure classification; the current default authenticator does not emit it.
`28` `ReasonIdempotencyConflict`	SEND	Repair the request first	Reserved	Reserved idempotency-conflict result; no current product path emits this value.
`29` `ReasonMessageSeqExhausted`	SEND	Repair the request first	Reserved	Reserved message-sequence-exhausted result; no current product path emits this value.

Prerequisites

Retain the packet type that carried the value instead of a bare number;
distinguish HTTP status, CONNACK, SENDACK, online delivery, and synchronization;
implement retries with idempotent identity, backoff, a cap, and cancellation;
redact identity and message content from logs and metrics.

Read the table

Phase identifies whether the value belongs to CONNECT/CONNACK, SEND/SENDACK, disconnect, or a compatible-path context.
Retry is a safe default, not permission for endless retries. Combine it with idempotent identity, backoff, a cap, and cancellation.
Reachability distinguishes values emitted by a current production path, values requiring a specific configuration/state, and compatible enum values not evidenced by the current golden path.
Presence in the enum does not mean every endpoint or SDK call can return the value.

Client processing order

Record packet type, numeric Reason Code, compatibility snapshot, and request correlation first.
Only explicit Success completes the current protocol phase.
Stop blind retries for identity, authorization, denylist/allowlist, ban, disband, invalid-field, or unsupported outcomes.
Retry route movement, rate limit, and system errors only with bounded exponential backoff, rediscovering required state first.
Fail closed on an unknown numeric value. Preserve it and never map it to Success.

Send outcome and message stages

For a persistent SEND, a successful SENDACK means the Channel authority made a successful durable-commit decision. It does not prove online receipt, RECVACK, webhook, plugin, offline synchronization, or product action.

A successful CONNACK means only that the current Gateway connection stage completed. The default v3 Beta composition does not yet automatically validate CONNECT against stored tokens, so it is not proof of production product identity.

Expected result

The golden sample records SENDACK success/failure and message sequence. Failure text preserves the raw Reason Code value so it can be interpreted with this table. The event log does not display token or Payload; a product UI maps its own localized product copy.

Troubleshooting

Value and name disagree: generation or version has drifted, and validation must fail.
A value marked unverified in the golden path appears: preserve the raw evidence and source revision; do not rewrite reachability to accommodate one observation.
A retryable result repeats: stop at the retry budget and inspect routing, rate limits, queue pressure, and cluster state.
An authorization result persists: correct the authoritative product account, membership, allowlist/denylist, or Channel state.
The value is unknown: treat it as failure and update the compatibility manifest and dictionary alignment.

Security and responsibility boundary

Reason Code handling must not disclose topology, risk decisions, or sensitive identity. Keep metric fields low-cardinality and exclude UID, token, Channel ID, and message body from metric labels. End-user language belongs to the product.

Next step

Return to Error Responses to combine HTTP and protocol handling, or observe the difference between SENDACK and synchronization in the Quickstart.

Reason Code

On this page