Status Events for JavaScript SDK
The PubNub JavaScript SDK reports connection and request outcomes as status categories, and only listeners added on the PubNub client with addListener({ status }) receive them. The categories that the subscription emits depend on the enableEventEngine setting, which defaults to true as of version 11.0.0.
1
For the properties of the status object and the method, refer to Add connection status listener. For the connection model behind these statuses, including reconnection policies, refer to SDK Connection Lifecycle.
Subscription statuses
The subscription emits the following statuses. To use the legacy subscription manager, set enableEventEngine: false.
- enableEventEngine: true (default)
- enableEventEngine: false (legacy)
| Status | Description | Introduced in version |
|---|---|---|
PNConnectedCategory | PubNub client subscribed and is ready to receive real-time updates. The SDK emits it when the subscription starts (handshake success). Channel or channel group mix changes emit PNSubscriptionChangedCategory. | before 4.0.6 |
PNDisconnectedCategory | PubNub client intentionally disconnected from the real-time updates stream. | before 4.0.6 |
PNDisconnectedUnexpectedlyCategory | PubNub client unexpectedly disconnected from the real-time updates stream. The status may contain an error field with more information. | 8.9.0 |
PNConnectionErrorCategory | PubNub client could not connect to the real-time updates stream. The SDK returns it when the previously started subscribe loop failed and the client disconnected from real-time data channels. Permission errors and a network outage can cause it. The status may contain an error field with more information. | before 4.0.6 |
PNSubscriptionChangedCategory | The mix of subscribed channels and channel groups changed. The status returns two arrays, one with all currently subscribed channels and one with all currently subscribed channel groups. | 9.5.0 |
Intermediate states such as connecting and reconnecting are handled internally and emit no status.
| Status | HTTP Code | Description |
|---|---|---|
PNConnectedCategory | 200 | PubNub client subscribed with a new mix of channels and is ready to receive real-time updates. The SDK emits it every time the channel or channel group mix changes and when the client first connects to the real-time updates stream. |
PNDisconnectedCategory | n/a | PubNub client intentionally disconnected from the real-time updates stream. |
PNReconnectedCategory | 200 | PubNub client reconnected to PubNub and is ready to receive real-time updates. |
PNRequestMessageCountExceededCategory | n/a | PubNub client exceeded the configured requestMessageCountThreshold (in-memory cache messages). It may suggest that you enable Message Persistence on the keyset. |
Request statuses
A failed request reports one of the following categories, regardless of the enableEventEngine value.
| Status | HTTP Code | Description |
|---|---|---|
PNNetworkIssuesCategory | n/a | PubNub client could not reach PubNub servers because the machine or device has no internet connection due to a network issue, or the client is behind a proxy. |
PNBadRequestCategory | 400 | PubNub answered the request with HTTP 400 because it is malformed. A missing publishKey, channel or message is reported as PNValidationErrorCategory instead, before the SDK sends anything. |
PNAccessDeniedCategory | 403 | PubNub client could not process a request because the authorization key does not have read permissions for the required resources (Access Manager permission failure). |
PNTimeoutCategory | n/a | PubNub client failed to connect to PubNub due to a timeout (the server did not respond within the specified time frame). |
PNUnknownCategory | Other | PubNub client received an unexpected response or encountered an error that it could not categorize. Common causes: aborted requests (check errorData for [Error: Aborted]), non-standard HTTP responses from proxies or VPNs, malformed JSON from intermediate actors, or unhandled HTTP status codes. Check the statusCode and errorData fields for details. |
PNCancelledCategory | n/a | PubNub client canceled the request. This happens when you explicitly cancel a request or when the browser or application aborts an in-flight request, for example during page navigation. |
PNValidationErrorCategory | n/a | PubNub client provided incomplete parameters for a particular endpoint, for example a missing publishKey, channel or message on publish. The SDK reports it without sending a request. |
PNMalformedResponseCategory | n/a | Defined in the SDK, but the JavaScript SDK does not currently report it. A 200 response with a body that is not JSON arrives as PNUnknownCategory with statusCode 0. |
PNServerErrorCategory | 5xx | PubNub server returned an error. It may indicate a temporary server issue or an ongoing incident. |
For the subscribe loop, the network issues, access denied, unknown, and malformed response categories arrive in the error field of a received PNConnectionErrorCategory or PNDisconnectedUnexpectedlyCategory status. A 403 during a subscription appears as PNConnectionErrorCategory with PNAccessDeniedCategory in the nested error field. If you receive it, verify that your Access Manager token has read permissions for the subscribed channels.
A failed request rejects with an error. Its status field holds the category and the HTTP status code:
1
Heartbeat failures
When you subscribe with withPresence: true and withHeartbeats: true, the SDK sends heartbeat requests. A failed heartbeat reaches the status listener like any other failed request. The status has operation set to PNHeartbeatOperation, error set to true, the request category, and the HTTP status code. A 400 response, for example, arrives as PNBadRequestCategory with statusCode 400.
Check operation and error to tell a heartbeat failure from the other statuses:
1
Browser-specific statuses
You can configure the SDK to emit the following additional statuses when the network status changes in the browser. The SDK emits the same browser-specific statuses regardless of the enableEventEngine value.
| Status | Description |
|---|---|
PNNetworkDownCategory | The internet connection is not available, or PubNub servers are not reachable. |
PNNetworkUpCategory | The internet connection is available, and PubNub servers are reachable. |
PNSharedWorkerUpdatedCategory | The SDK noticed a newer shared worker. Refer to Share subscriptions across browser tabs. |
Migrating to the new subscription loop
Upgrading from a version before 11.0.0, where enableEventEngine defaulted to false, changes only the status categories that the subscription emits. The new subscription loop (enableEventEngine: true) emits fewer categories, adds richer error detail, and no longer reuses PNConnectedCategory for reconnects. If your listeners do not inspect PNConnectedCategory beyond detecting the initial connection, no change is required.
| Before (legacy) | After (new subscription loop) |
|---|---|
PNConnectedCategory fires on every subscription change (adding or removing channels or channel groups). | PNConnectedCategory fires only when the subscription starts. Later channel mix changes emit PNSubscriptionChangedCategory. |
If your application treats PNConnectedCategory as "subscription list changed" or runs logic on every subscribe or unsubscribe, move that logic to PNSubscriptionChangedCategory and keep PNConnectedCategory for the initial subscription start.
- Before (legacy: PNConnectedCategory on every change)
- After (new subscription loop)
1
1
The new subscription loop also reports PNDisconnectedUnexpectedlyCategory and PNConnectionErrorCategory. Use their error field for diagnostics.
For the full list of changes in version 11.0.0, refer to the JavaScript SDK 11.0.0 migration guide.