Status Events for Java SDK

Subscription loop

These status events apply to the subscription loop introduced in version 6.4.5 and enabled by default in version 9.0.0.

The PubNub Java SDK provides status events to notify you about the state of the SDK through the PNStatusCategory enum and PubNubException types.

Subscription-related statuses

The PNStatusCategory enum defines the following subscription-related values:

Status	Description
PNConnectedCategory	The connection has been established and is ready to receive real-time updates.
PNDisconnectedCategory	The connection has been intentionally terminated.
PNUnexpectedDisconnectCategory	The connection was unexpectedly lost, with details about the error. This status may also mean that the reconnection attempts were unsuccessful.
PNConnectionError	Failed to establish the initial connection, with details about the error. This status may also mean that the reconnection attempts were unsuccessful.
PNSubscriptionChanged	The mix of subscribed channels and channel groups has changed. This event returns two lists: one with all subscribed channels and the second with all subscribed channel groups. It does not include channels and groups that have been just subscribed.

Previous status categories

Status	Description	Removed in version
PNReconnectedCategory	SDK was able to reconnect to PubNub. Now handled internally without specific status.	9.0.0
PNAcknowledgmentCategory	Used API report success with this status category. Now handled with operation-specific success callbacks.	9.0.0
PNTimeoutCategory	Used API didn't receive a response from the server in time. Now represented by PubNubException with code 100.	9.0.0
PNRequestMessageCountExceededCategory	Received more messages than specified by requestMessageCountThreshold. No direct equivalent; use operation-specific callbacks.	9.0.0
PNReconnectionAttemptsExhausted	The subscribe loop has been stopped due to maximum reconnection exhausted. Now represented as PNConnectionError with specific exception.	9.0.0
PNMalformedResponseCategory	PubNub sent a malformed response. This may happen when you connect to a public WiFi that requires you to log in via your web browser first, there is a proxy somewhere returning an HTML access denied error, or if there was an intermittent server issue. This status category is not actively emitted. Malformed responses now trigger a PNUnexpectedDisconnectCategory status with appropriate error details.	Not removed

SDK connection lifecycle

Intermediate states like connecting and reconnecting are now handled internally without emitting specific statuses. For more general information on statuses and reconnection policies, refer to SDK Connection Lifecycle.

Other statuses

The SDK provides specific statuses for heartbeat operations:

Status	Description
PNHeartbeatSuccess	A background implicit Heartbeat request was successful.
PNHeartbeatFailed	A background implicit Heartbeat request attempt failed.

Heartbeat notification control

You can control which heartbeat notifications you receive using the PNHeartbeatNotificationOptions enum:

• NONE: Do not report heartbeat events
• FAILURES: Receive only failed heartbeat events
• ALL: Receive all heartbeat events

Error events

The Java SDK uses PubNubException to provide detailed error information. Most errors are returned in the exception property of the PNStatus object.

Common error types

Error Code	Message	Description
100	Timeout Occurred	An asynchronous operation timed out.
102	Connect Exception	Please verify if the network is reachable.
103	HTTP Error	Please check network connectivity.
121	JSON Error	Error while processing API response.
125	Internal Error	An internal SDK error occurred.
126	Parsing Error	Error while parsing data.
131	Invalid arguments	At least one request parameter is invalid.
135	Crypto Error	Error while encrypting/decrypting message. Please contact support with error details.

Key-related errors

Error Code	Message	Description
138	Subscribe Key Missing	ULS configuration failed. Subscribe Key not configured.
139	Publish Key Missing	ULS configuration failed. Publish Key not configured.
114	Secret Key Missing	ULS configuration failed. Secret Key not configured.

Resource errors

Error Code	Message	Description
132	Channel Missing	A required channel parameter is missing.
136	Group Missing	A required channel group parameter is missing.
141	Channel and Group Missing	Both channel and channel group parameters are missing.
142	Message Missing	A required message parameter is missing.
140	State Missing	A required state parameter is missing.
144	Device ID Missing	A required device ID parameter is missing.
143	Push Type Missing	A required push type parameter is missing.
145	Timetoken Missing	A required timetoken parameter is missing.