Status Events for Mbed SDK

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 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 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 logging to maximum will output a lot of data useful in diagnosing the cause of errors/failures.

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 defined):

StatusDescriptionIntroduced 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 regardless of which subscription architecture is used:

Symbol/CodeDescriptionUser actionIntroduced 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:

StatusDescriptionUser actionIntroduced 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/CodeDescriptionUser actionIntroduced 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 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 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/CodeDescriptionUser actionIntroduced 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/CodeDescriptionUser actionIntroduced 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 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/CodeDescriptionUser actionIntroduced 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/CodeDescriptionUser actionIntroduced 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/CodeDescriptionUser actionIntroduced 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/CodeDescriptionUser actionIntroduced 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
Last updated on