Status Events for Python-Asyncio SDK

Subscribe loop

These status events apply to the newer subscribe loop introduced in version 7.4.0 and enabled by default in version 8.0.0.

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


StatusDescriptionIntroduced in version
PNConnectedCategory
The connection has been established and is ready to receive real-time updates.
Introduced in 4.0.0, behavior changed in 10.3.0
PNDisconnectedCategory
The connection has been intentionally terminated.
Introduced in 4.0.0, behavior changed in 10.3.0
PNUnexpectedDisconnectCategory
The connection was unexpectedly lost. This occurs when the previously started subscribe loop fails and the client disconnects from real-time data channels.
Introduced in 4.0.0, behavior changed in 10.3.0
PNConnectionErrorCategory
Failed to establish the initial connection, with details about the error. This event is also emitted during connection failures in reconnect scenarios.
10.3.0
PNSubscriptionChangedCategory
The mix of subscribed channels and channel groups has changed.
10.3.0

Previous status categories

StatusDescriptionIntroduced in versionBehavior changed in version
PNReconnectedCategory
SDK was able to reconnect to PubNub. In the newer subscribe loop, reconnection is handled with more granular statuses.
4.0.0
7.4.0, 10.3.0 (enhanced)
PNAcknowledgmentCategory
An API call was successful. This status has additional details based on the type of the successful operation. Also used in various transitions in the newer subscribe loop.
4.0.0
7.4.0, 10.3.0 (enhanced)
PNTimeoutCategory
Processing has failed because of request time out.
4.0.0
No significant change
PNNetworkIssuesCategory
The SDK isn't able to reach PubNub servers due to network connectivity issues.
4.0.0
10.3.0 (partially replaced by PNConnectionErrorCategory)
PNCancelledCategory
Emitted when a subscribe operation is cancelled.
4.0.0
No significant change
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 additional statuses for various operations:

StatusDescription
PNAccessDeniedCategory
The SDK will announce this error when the Access Manager does not allow the operation. Indicates authorization failures, typically due to invalid keys or token.
PNBadRequestCategory
PubNub API server was unable to parse SDK request correctly or request is missing required parameters like subscribe key or publish key.
PNMalformedFilterExpressionCategory
Emitted when a filter expression is malformed.
PNMalformedResponseCategory
Emitted when the server response is malformed.
PNDecryptionErrorCategory
Emitted when a message decryption error occurs, usually due to incorrect crypto key. Added in 4.5.4.
PNTLSConnectionFailedCategory
Emitted when a TLS connection fails, indicating secure connection issues.
PNTLSUntrustedCertificateCategory
Emitted when a TLS certificate is untrusted.
PNInternalExceptionCategory
Emitted for internal exceptions.
PNUnknownCategory
Returned when the subscriber gets a non-200 HTTP response code from the server or for unknown error types.

Error handling

The Python SDK uses PNStatus to provide detailed error information. When handling errors, you'll encounter various status categories like PNNetworkIssuesCategory for connectivity issues, PNTimeoutCategory for request timeouts, and PNConnectionErrorCategory for connection failures.

The status object contains properties to help identify and handle errors:

PropertyDescription
category
The PNStatusCategory value identifying the type of status event.
error
Boolean indicating if this status represents an error.
error_data
Contains detailed error information when an error occurs.
affected_channels
List of channels affected by this status event.
affected_groups
List of channel groups affected by this status event.
status_code
HTTP status code if applicable.
operation
The operation type that triggered this status.
tls_enabled
Boolean indicating if TLS was enabled for this operation.
uuid
The UUID associated with this operation.
auth_key
The authentication key used for this operation.
Last updated on