Status Events for C-Core SDK (legacy)
New SDK available
C-Core (legacy) is still supported. If you are starting a new project, use the new C SDK.
The PubNub C-Core (legacy) library reports status codes that describe operation outcomes and connection state. This page explains the key categories and recommended handling strategies.
Subscribe loop
Some status codes only apply to the latest subscription architecture introduced in version 4.14.0 which you can enable with PUBNUB_USE_SUBSCRIBE_EVENT_ENGINE.
The PubNub C-Core (legacy) library provides status codes to notify you about the state of operations through the pubnub_res enum for general statuses and the pubnub_subscription_status enum for subscription events when using the latest subscription architecture.
No status codes have been removed or deprecated from the C-Core (legacy) library. The library has evolved by adding new status codes as new features and APIs have been implemented.
General error handling
For all of these status codes, you can use the pubnub_should_retry() function (and its wrapper, member function should_retry() in C++) to determine if it makes sense to retry the operation after encountering a particular error.
To get a string describing a C-core status code, call pubnub_res_2_string(). Also, increasing the C-Core (legacy) logging to maximum will output a lot of data useful in diagnosing the cause of errors/failures.
Detailed logging for troubleshooting
When dealing with unexpected status codes or transaction failures, detailed logging can significantly help with diagnostics. Increasing the C-Core (legacy) logging level to maximum (PUBNUB_LOG_LEVEL_TRACE) will output comprehensive data useful for identifying the root cause of errors.
For complete information about configuring log levels, customizing log output, and implementing different logging strategies, refer to the Logging document.
Subscription-related statuses
Subscribe loop
These status codes only apply to the newer subscription architecture (enabled with PUBNUB_USE_SUBSCRIBE_EVENT_ENGINE) introduced in version 4.14.0.
Latest subscription architecture statuses
The pubnub_subscription_status enum defines the following subscription-related values (only when PUBNUB_USE_SUBSCRIBE_EVENT_ENGINE is used):
| Status | Description | Introduced in version |
|---|---|---|
PNSS_SUBSCRIPTION_STATUS_CONNECTED | The connection has been established and is ready to receive real-time updates. | 4.14.0 |
PNSS_SUBSCRIPTION_STATUS_DISCONNECTED | The connection has been intentionally terminated. | 4.14.0 |
PNSS_SUBSCRIPTION_STATUS_DISCONNECTED_UNEXPECTEDLY | The connection was unexpectedly lost. The subscribe_status_change_listener will receive a pubnub_subscription_status_data_t structure that includes a reason field containing the specific error code (a pubnub_res enum value) detailing why the connection was lost. | 4.14.0 |
PNSS_SUBSCRIPTION_STATUS_CONNECTION_ERROR | Failed to establish the initial connection. Similar to unexpected disconnection, the subscribe_status_change_listener will receive status data with a reason field (of type pubnub_res) explaining the specific error. | 4.14.0 |
PNSS_SUBSCRIPTION_STATUS_SUBSCRIPTION_CHANGED | The mix of subscribed channels and channel groups has changed. | 4.14.0 |
Subscription management statuses
The following statuses are returned when managing subscription objects and may be encountered when PUBNUB_USE_SUBSCRIBE_EVENT_ENGINE is used.
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_SUB_ALREADY_ADDED | Subscription object already exists in subscription set. Returned when attempting to add a subscription (pubnub_subscription_t) that is already part of a subscription set (pubnub_subscription_set_t). | Use a different subscription object or remove the existing one from the set. | 4.14.0 |
PNR_SUB_NOT_FOUND | Subscription object not found in subscription set. This occurs either when trying to access a subscription that isn't in the set, or when attempting to unsubscribe using a subscription or subscription set that wasn't previously used with subscription. In the latter case, you only need to ensure resources are released. | Make sure you're using a valid subscription that has been added to the set, or confirm that resource cleanup is handled appropriately. | 4.14.0 |
SDK connection lifecycle
When using the latest subscription architecture, transitioning between subscription states is handled automatically, with status notifications emitted at key points in the lifecycle. For more details, refer to SDK Connection Lifecycle.
Subscription process statuses
All of the following pubnub_res values remain valid across both subscription architectures and can appear in different contexts:
| Status | Description | User action | Introduced in version |
|---|---|---|---|
PNR_OK | Transaction success. This is a common status returned by all APIs, including subscription functions like pubnub_subscribe_with_subscription(). | Proceed with business as usual. | Early versions (pre-2.0) |
PNR_SUB_TT_FORMAT_ERROR | Subscribe Time token not in expected format. This may be part of the reason field in status data for subscription error events. | Report to PubNub if you encounter this with official SDKs. | ~2.x |
PNR_SUB_NO_TT_ERROR | No Time token in the subscribe response. May appear as a reason for subscription errors. | Report to PubNub if you encounter this with official SDKs. | ~2.x |
PNR_SUB_NO_REG_ERROR | No Region in the subscribe response. May appear as a reason for subscription errors. | Report to PubNub if you encounter this with official SDKs. | ~2.x |
PNR_GROUP_EMPTY | No Channels in the ChannelGroup. May appear as a reason for subscription errors. | Add channels to the channel group before subscribing to it. | 3.3.0 |
Common error statuses
The pubnub_res enum provides the following common error statuses:
Network & communication errors
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_ADDR_RESOLUTION_FAILED | PubNub host name resolution failed. We failed to get an IP address from the PubNub host name (origin). Most of the time, this comes down to a DNS error. | Check your network, focusing on DNS issues. | Early versions (pre-2.0) |
PNR_WAIT_CONNECT_TIMEOUT | Time-out before the TCP connection was established. This is reported for a time-out detected by PubNub client itself. | Check your network connection and consider increasing the connection timeout. | ~2.x |
PNR_CONNECT_FAILED | Connecting to PubNub server failed. Most often, this means a network outage, but could be many things. If using SSL/TLS, it could be some of its errors. | Check your network including any firewall/proxy. If using SSL/TLS, check the errors reported, try using fallback. | Early versions (pre-2.0) |
PNR_CONNECTION_TIMEOUT | A time-out happened in the network. Mostly, this is because a network outage happened while being connected to the PubNub server, but could be other things. | Treat this similarly to PNR_CONNECT_FAILED, but focus more on hardware / low level IP issues. | Early versions (pre-2.0) |
PNR_TIMEOUT | Time-out before the request has completed. This is reported for a time-out detected by PubNub client itself, not some reported by others (i.e. the TCP/IP stack). | Increase the transaction timeout you used. If that doesn't help, treat it like PNR_CONNECTION_TIMEOUT. | Early versions (pre-2.0) |
PNR_ABORTED | Connection to PubNub aborted (in most cases, a TCP reset was received). | This is very unlikely, unless you're using a proxy - in which case, check the proxy. If not using proxy, please report this to PubNub. | Early versions (pre-2.0) |
PNR_IO_ERROR | Communication error (network or HTTP response format). | If you're using a proxy, please check the proxy. Otherwise, this indicates some SW error, possibly problem in C-Core (legacy) itself. Please report this to PubNub. | Early versions (pre-2.0) |
PNR_HTTP_ERROR | An error reported in HTTP status code, not detected by some other means. | This is a fallback to the cases that C-Core (legacy) hasn't covered yet. Call pubnub_last_http_code() to get the error code. Also, read the actual response to understand what was the problem. | Early versions (pre-2.0) |
Transaction control
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_CANCELLED | User cancelled a transaction. | If you haven't cancelled a transaction, please report this to PubNub. | Early versions (pre-2.0) |
PNR_STARTED | Transaction started - this is not an error code, but information/status code. | Await the final outcome. | Early versions (pre-2.0) |
PNR_IN_PROGRESS | Transaction (already) ongoing. Can't start a new transaction while the old one is in progress. | Await the final outcome of the current transaction or start it in another context. | Early versions (pre-2.0) |
Data format & buffer management
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_FORMAT_ERROR | Unexpected input in received JSON. | If using a proxy, please check the proxy. Otherwise, this is most likely an error in C-Core (legacy) parsing, so please report this to PubNub. | Early versions (pre-2.0) |
PNR_RX_BUFF_NOT_EMPTY | Receive buffer (from previous transaction) not read, new subscription not allowed. | Read the whole receive buffer. | Early versions (pre-2.0) |
PNR_TX_BUFF_TOO_SMALL | The transmit buffer is too small. | Increase #PUBNUB_BUF_MAXLEN or divide your message to multiple segments. | Early versions (pre-2.0) |
PNR_REPLY_TOO_BIG | Reply is too big to fit in our reply buffer. This same error is reported if the reply buffer is statically or dynamically allocated. | If using statically allocated buffer, increase the buffer size. Otherwise, this indicates you need more RAM. | Early versions (pre-2.0) |
PNR_OUT_OF_MEMORY | Ran out of dynamic memory. | Free up memory resources or increase the memory allocation pool. | ~2.x |
PNR_BAD_COMPRESSION_FORMAT | Bad compression format or compressed data corrupted. | Check that your data is properly compressed or avoid using compression for this data. | ~2.x |
Parameter validation
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_INVALID_CHANNEL | Channel specification / name is invalid. | Use a valid channel name/specification. | Early versions (pre-2.0) |
PNR_INVALID_PARAMETERS | Invalid input parameters passed to a given function. | Review the function documentation and provide valid parameters. | ~2.x |
Security & authentication
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_ACCESS_DENIED | Access/Permission denied. | Check that you have the proper access rights for the requested operation. | Before 3.3.0 |
PNR_AUTHENTICATION_FAILED | Proxy authentication failed. | Verify the proxy authentication credentials. | ~2.x |
PNR_CRYPTO_NOT_SUPPORTED | Encryption (and decryption) not supported. | Switch to a platform that supports encryption/decryption (like OpenSSL) or don't use it. | Early versions (pre-2.0) |
API-specific errors
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_PUBLISH_FAILED | Publish transaction failed - error returned from PubNub. | To see the reason describing the failure, call pubnub_last_publish_result(). | Early versions (pre-2.0) |
PNR_CHANNEL_REGISTRY_ERROR | A transaction related to channel registry failed - error returned from PubNub. | To see the reason describing the failure, get the value for key message from the response (which is a JSON object) and value for key status for the numeric code of the error. | ~2.x |
PNR_OBJECTS_API_INVALID_PARAM | Objects API invalid parameter. | Check the parameters passed to the Objects API method. | 3.0.0 |
PNR_OBJECTS_API_ERROR | Objects API transaction reported an error. | Review the request parameters and server response for more details. | 3.0.0 |
PNR_GOT_ALL_ACTIONS | Actions API pbcc_get_actions_more() did not find another hyperlink to the rest. | This is not an error but an indication that all actions have been retrieved. | 3.0.0 |
PNR_ACTIONS_API_ERROR | Actions API transaction reported an error. | Review the request parameters and server response for more details. | 3.0.0 |
PNR_GRANT_TOKEN_API_ERROR | Grant Token API transaction reported an error. | Review the request parameters and server response for more details. | 3.1.0 |
PNR_FETCH_HISTORY_ERROR | Fetch History API transaction reported an error. | Review the request parameters and server response for more details. | 4.0.0 |
PNR_REVOKE_TOKEN_API_ERROR | Revoke Token API transaction reported an error. | Review the request parameters and server response for more details. | 3.3.0 |
Miscellaneous
| Symbol/Code | Description | User action | Introduced in version |
|---|---|---|---|
PNR_INTERNAL_ERROR | An internal error in processing. | Please report to PubNub. | Early versions (pre-2.0) |
PNR_ERROR_ON_SERVER | Server reports an error in the response. | Check the response for specific error details from the server. | ~2.x |