Status Events for Java SDK
The PubNub Java Software Development Kit (SDK) reports status events that describe connection state and error conditions. This page explains each status category and when it appears.
Subscribe loop
These status events apply to the latest subscription loop architecture introduced 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 a specific status. For more information on reconnection, refer to Configuration. | 9.0.0 |
PNAcknowledgmentCategory | An API call was successful. This status has additional details based on the type of the successful operation. Now handled with operation-specific success callbacks. For more information on the channels and channel groups you've subscribed to, refer to the PNSubscriptionChanged status. | 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 eventsFAILURES: Receive only failed heartbeat eventsALL: 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. |