Connection Management

All PubNub SDKs manage the connection for you, so you don't have to handle device- or platform-specific details. To get the most from PubNub, understand when an SDK creates connections and how to recover from network errors.

Get connected

When you initialize a PubNub object, no connection exists yet. The object lets you call PubNub APIs such as Publish and Subscribe. The first API call creates the connection. The network returns success (with data) or an error.

Successful requests return HTTP status 200. Errors return codes such as 400, 404, 413, 414, or 500. You don't need to read these codes directly because SDKs surface them as status events in the status handler of your listener. Handling status events is the key to graceful recovery.

Handle network interruptions

PubNub's automatic reconnection handles brief interruptions such as tunnels or switching from Wi‑Fi to cellular. Autoreconnect delivers messages published during a dropped connection.

The default message queue size is 100 and each message persists for up to 20 minutes. If you publish more than 100 messages, older messages overflow and are discarded. Overflow discards the oldest messages (FIFO) during the drop.

To guarantee message availability, use Message Persistence to retrieve historical messages.

Connection types

There are two connection types: subscribe and non‑subscribe. A subscribe connection is for the Subscribe API. A non‑subscribe connection is for other APIs such as Publish, Here Now, and History.

Subscribe connections

A subscribe request creates a long‑lived connection. The PubNub SDK sends an HTTP request to the PubNub Network with a list of channels to receive messages. When any client sends a message to one of those channels, the network responds with the message content and status 200. The SDK continues to issue subscribe requests after each success.

If no messages arrive within 280 seconds (long‑poll expiration), the network returns 200 with no messages. The SDK then sends the next subscribe request.

This request/response cycle continues for the life of the client's PubNub instance.

I’m Edward. I lead a small engineering team. We built a real-time collaboration platform for schools so students, teachers, and parents can share messages and materials across devices.

School networks are tough: older hardware, mixed browsers, and proxies or firewalls that block traffic. We also needed to scale to tens of thousands of concurrent students. My team wanted to focus on product, not real-time plumbing.

We chose PubNub instead of running our own servers. PubNub scales globally and delivers messages quickly. It helps with connection disruptions and mobile. PubNub also supports HTTP long polling for legacy and low‑bandwidth environments. Long polling lets clients re‑establish connections automatically and receive data when it becomes available or when the timeout is reached.

PubNub let us support legacy systems without giving up scale.

Battle short attention span with long polling

Non-Subscribe connections

A non‑subscribe connection is short‑lived. The SDK sends an HTTP request and the PubNub Network responds, typically within milliseconds (depends on the request).

Custom domain

To optimize integration or meet branding and compliance needs, you can use a custom domain for PubNub endpoints. See Use a custom domain.

Connection timeout

All APIs except Subscribe have a connection timeout of 15 seconds (may vary by SDK). If the PubNub Network doesn't respond within the configured time, the SDK aborts and reports a timeout status event (PNTimeoutCategory).

Timeout troubleshooting

Troubleshooting a timeout can be hard because the source may be the app, device, network, DNS, ISP, or the PubNub Network.

PubNub provides logs to help find the root cause. If the request never reaches the PubNub Network, add logging on all points of your path. Tools like Catchpoint (a network monitoring service) can also help.

Timeout configuration

Adjust the 15‑second default if needed. For example, if you publish stock prices every 250 ms, a 15‑second wait isn't helpful. A single publish may not matter because it’s quickly outdated. In that case, use a shorter timeout.

Connection timeout

See each SDK's configuration docs for the connectionTimeout option.

Subscribe

The first time you call Subscribe, the SDK opens a TCP socket and sends the request. If it succeeds, the SDK emits PNConnectedCategory (name may vary by SDK). See the connection status listener (for example, Kotlin API).

The status event includes all channels successfully subscribed in that request.

SDKs

The event payload may vary across SDKs.

{
    "category": "PNConnectedCategory",
    "operation": "PNSubscribeOperation",
    "affectedChannels": ["ch1", "ch2"],
    "subscribedChannels": ["ch1", "ch2"],
    "affectedChannelGroups": [],
    "lastTimetoken": 0,
    "currentTimetoken": "15856996387695942"
}

If you were to make another subscribe request to new channels, the status event would only include those new channels, however your client is still subscribed to the previous channels.

{
    "category": "PNConnectedCategory",
    "operation": "PNSubscribeOperation",
    "affectedChannels": ["ch3", "ch4"],
    "subscribedChannels": ["ch1", "ch2", "ch3", "ch4"],
    "affectedChannelGroups": [],
    "lastTimetoken": "15856996387695942",
    "currentTimetoken": "15856996387695942"
}

When you unsubscribe from one of those channels, the status event would not include a category for that but there is an operation.

{
    "error": false,
    "operation": "PNUnsubscribeOperation",
    "statusCode": 200,
    "affectedChannels": ["ch1", "ch2"],
    "affectedChannelGroups": [],
    "currentTimetoken": "15856996387695942",
    "lastTimetoken": "15856996387695942"
}

You don't need to monitor this event unless you want confirmation that the unsubscribe succeeded.

Connection issues

Network errors can occur. Make sure your app covers edge cases. Here are common issues.

Connection drop

The SDK detects this and emits a status event to your Status handler:

{"category":"PNNetworkDownCategory"}

At this point, notify the user about connectivity issues. The app is disconnected and can't perform PubNub operations or other network calls.

Simulate a network disconnection

You can simulate a drop using your browser's dev tools by switching the network to Offline.

Reconnection

When the connection returns, the browser detects it and the SDK emits PNNetworkUpCategory to your Status handler:

{"category":"PNNetworkUpCategory"}

Restore channels subscription

For the browser, you can configure the JavaScript SDK to resubscribe to the same channels it was previously subscribed to before the connection issue occurred using the restore configuration property. When enabled, the JavaScript SDK caches the currently subscribed channels automatically and subscribes to the same channels it was before the network went down. Background means the user switches apps or locks the device. Foreground means the user brings the app on screen.

However, if this property is false, subscribe to those channels manually when the PNNetworkUpCategory event occurs. Keep track of the channels in local cache.

Automatic resubscribing only in JavaScript

Automatic resubscribe works only for the JavaScript SDK in a browser.

Other SDKs detect failures or timeouts and enter reconnection policy mode.

SDK connection lifecycle

PubNub SDKs use standardized workflows for subscribe and presence loops and implement configurable auto‑retry policies for network issues. This ensures stable, predictable connections across languages.

When you call any subscribe method in the PubNub SDK, an internal mechanism called the subscribe loop is automatically initiated. This is a core part of PubNub's real-time functionality:

• The loop runs inside the SDK; you don't need to start or maintain it.
• It maintains a persistent connection to PubNub servers and automatically reconnects if the network drops.
• It receives and processes incoming messages, delivering them to your handlers or callbacks.
• It's optimized for minimal battery and network usage while remaining real‑time.

When you unsubscribe or call methods like unsubscribeAll(), the SDK automatically stops the subscribe loop for those channels.

Some lower-level SDKs expose direct control of the subscribe loop, but these are for advanced use cases only and aren't needed for typical implementations.

Understanding the subscribe loop

Automatic reconnection and permissions

SDKs don't automatically reconnect when Access Manager tokens expire. For token lifecycle handling, see Access Manager.

SDK statuses

During your application's lifecycle, there are a few statuses the SDK may emit that you can use to determine the state of the workflow. This section focuses on the statuses that are relevant to the subscribe workflow, but there are other statuses that are relevant to other workflows.

Differences across SDKs

Not all SDKs emit all of the statuses, and some may present the additional error information differently. Consult your SDK's Status events documentation (for example, in JavaScript) for more information.

Status	Description
Connected	The workflow is running, and messages/events are being received.
Disconnected	The workflow isn't running; no messages arrive. Emitted only after a connection was established (Connected was emitted). If you call disconnect(), call reconnect() to resume. Calling subscribe() alone won't reconnect.
Connection error	The workflow isn't running because retries reached the maximum attempts while trying to connect. No messages arrived because the connection wasn't established. Includes an error object explaining why the connection failed.
Disconnected unexpectedly	The workflow isn't running because, after receiving messages, the client disconnected and retries reached the maximum attempts when trying to reconnect. Includes an error object explaining why the client disconnected without user request.
Subscription changed	The SDK subscribed to new channels or channel groups. Triggered each time the channel or channel‑group mix changes after the initial connection. Includes the current list of subscribed channels and channel groups.

Reconnection policy

You can configure the automatic reconnection behavior of the SDK when you initialize the PubNub object. There are several configuration options (policies) available:

• Linear: retry connection at set intervals for a set number of attempts
• Exponential: retry connection at exponentially longer intervals for a set number of attempts

Reconnecting and usage

Retries don't count as transactions because none reach the PubNub network until one succeeds. At that point, retries stop.

Default reconnection policy

By default, PubNub SDKs are configured to exponentially retry subscribe operations only. The subscribe connection is retried up to 6 times with the delay between failed attempts ranging from 2 to 150 seconds.

SDK reconnection policy parity

Certain SDKs do not retry subscribe operations by default. For more information on which operations are retried, refer to your SDK's configuration documentation, for example, JavaScript, Kotlin, or Python.

Reconnection policy details

The maximum number of reconnect attempts is 10 for linear and 6 for exponential. The minimum retry interval for all policies is 2 seconds. A random break from 0,001 to 0,999 seconds is added to each retry attempt.

Linear

The linear reconnection policy has several configurable parameters. The table below uses Rust as an example, but note that the syntax and data types may differ across SDKs.

Parameter	Description
delay Type: u64	The delay in seconds between failed retry attempts.
max_retry Type: u8	Number of times a request can be retried.
excluded Type: Option<Vec<Endpoint>>	Endpoints that won't be retried. Refer to Exclude endpoints from auto retry for more information.

Exponential

The exponential backoff starts at i = 0 and increases as min_delay*2^i until the max retry attempts. The interval never exceeds max_delay. Parameters:

Parameter	Description
min_delay Type: u64	Minimum delay in seconds between failed retry attempts.
max_delay Type: u64	Maximum delay in seconds between failed retry attempts.
max_retry Type: u8	Number of times a request can be retried.
excluded Type: Option<Vec<Endpoint>>	Endpoints that won't be retried. Refer to Exclude endpoints from auto retry for more information.

Exclude endpoints from auto retry

Our SDKs also let you exclude endpoints (features) from the retry policy. Excluding an endpoint turns off auto‑retry for that endpoint. See each SDK's documentation for details.

JavaScript

// Example: Exclude the Message Send endpoint from auto retry using Linear policy
const pubnub = new PubNub({
  subscribeKey: "demo",
  publishKey: "demo",
  userId: "user123",
  retryConfiguration: PubNub.LinearRetryPolicy({
    delay: 3, // 3 seconds delay between retry attempts
    maximumRetry: 5, // Maximum 5 retry attempts
    excluded: [PubNub.Endpoint.MessageSend] // Exclude MessageSend endpoint
  })
});

// Example: Exclude multiple endpoints using Exponential policy
const pubnub = new PubNub({
  subscribeKey: "demo",

show all 24 lines

Swift

// Example: Exclude an endpoint using Linear policy
let config = PubNubConfiguration(
  publishKey: "demo",
  subscribeKey: "demo",
  userId: "user123",
  automaticRetry: AutomaticRetry(
    policy: .linear(delay: 3.0),
    retryLimit: 5,
    excluded: [.messageSend]
  )
)
let pubnub = PubNub(configuration: config)

// Example: Exclude multiple endpoints using Exponential policy
let config = PubNubConfiguration(

show all 25 lines

Objective-C

// Example: Exclude an endpoint using Linear policy
PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo" 
                                                         subscribeKey:@"demo"
                                                              userId:@"user123"];

// Linear policy with excluded endpoints
config.requestRetry = [PNRequestRetryConfiguration configurationWithLinearDelay:3.0
                                                                  maximumRetry:5
                                                             excludedEndpoints:PNMessageSendEndpoint, 0];

// Example: Exclude multiple endpoints using Exponential policy
config.requestRetry = [PNRequestRetryConfiguration configurationWithExponentialDelay:2.0
                                                                       maximumDelay:60.0
                                                                       maximumRetry:6
                                                                  excludedEndpoints:PNMessageSendEndpoint, PNMessageStorageEndpoint, 0];

show all 17 lines

Java

// Example: Exclude the Subscribe endpoint using Linear policy
PNConfiguration config = new PNConfiguration("user123");
config.setSubscribeKey("demo");
config.setPublishKey("demo");
config.setRetryConfiguration(
    RetryConfiguration.linear(
        3, // 3 seconds delay between retries
        5, // Maximum 5 retry attempts
        Collections.singletonList(RetryableEndpointGroup.SUBSCRIBE) // Exclude Subscribe endpoint
    )
);
PubNub pubnub = new PubNub(config);

// Example: Exclude multiple endpoints using Exponential policy
PNConfiguration config = new PNConfiguration("user123");

show all 26 lines

Rust

// Example: Exclude the Publish endpoint from auto retry using Linear policy
let keyset = Keyset {
    subscribe_key: "demo".to_owned(),
    publish_key: Some("demo".to_owned()),
    secret_key: None,
};

let client = PubNubClientBuilder::with_transport(Transport::with_reqwest())
    .with_keyset(keyset)
    .with_user_id("user123")
    .with_retry_configuration(RequestRetryConfiguration::Linear {
        delay: 3,  // 3 seconds delay between retries
        max_retry: 5,  // Maximum 5 retry attempts
        excluded_endpoints: Some(vec![Endpoint::Publish])  // Exclude Publish endpoint
    })

show all 28 lines

C-Core

// Example: Exclude endpoints from auto retry using Linear policy
pubnub_retry_configuration_t* config =
    pubnub_retry_configuration_linear_alloc_with_excluded(
        PNRC_MESSAGE_SEND_ENDPOINT,  // Exclude Message Send endpoint
        PNRC_MESSAGE_STORAGE_ENDPOINT,  // Exclude Message Storage endpoint
        -1  // End of list marker
    );

// Apply configuration to PubNub context
pubnub_set_retry_configuration(pubnub, config);

// Example: Exclude endpoints with custom parameters using Exponential policy
pubnub_retry_configuration_t* config =
    pubnub_retry_configuration_exponential_alloc_with_options(
        2,  // Minimum delay between retries (2 seconds)

show all 27 lines

Mobile App connection management

Mobile apps can run on screen or in the background. Use these tips to manage connections on mobile and ensure you receive the messages you care about.

Mobile App connection use cases

Consider the following scenarios:

• Scenario 1: the app runs in background (offscreen), then returns to foreground. You want to catch up on messages sent while offscreen.
• Scenario 2: the app runs in background and loses connectivity. You want to notify the user about unread messages when the device goes online.
• Scenario 3: a gaming app goes offline briefly and reconnects. You want to show only the latest messages.

Scenario 1

Goal: catch up on all messages sent while the app was in background.

First decide whether the app can unsubscribe from channels (and send a leave event) when going to background. If you keep subscriptions, catch‑up is still possible but more complex.

More Information

For more information about unsubscribing and presence events, refer to Channel Subscriptions and Presence Events.

With unsubscribing

If your app can unsubscribe as it transitions to the background, the overall flow of message catch-up might look as follows:

1. Your app keeps track of the last received message timetoken using a listener.
2. On transition to background, your app unsubscribes from all channels.
3. On transition to foreground, your app receives and caches new messages, but doesn't process them. At the same time, your app performs a Message Persistence API request to fetch all messages sent since the last received message (increment the timetoken your app saved in the first step by 1 and use that as the end parameter). Note that you might need to paginate through the results when the number of missed messages may be high. To get the subsequent page, use the same end parameter and update start to be the earliest (smallest) timetoken received from the previous page. Continue to do that until you get 0 messages.
4. Send a subscribe call and use the latest (highest) timetoken received in the previous step to start subscribing to the channels/channel groups again.

Without unsubscribing

If your app can't unsubscribe as it goes to background, the flow may look like this:

1. Your app keeps track of the last received message timetoken using a listener.
2. On transition to background, your app does nothing with regards to channels.
3. On transition to foreground, your app performs a Message Persistence API request to fetch all messages sent since the last received message and store these messages / events without triggering code to handle them. Message Persistence should consider different channels.
4. Continue paginating though history until all messages from all channels have been stored.
5. When your app has stored all messages/events, handle them according to your business logic.

Scenario 2

Goal: send a push notification about unread messages while the app was offline in background.

Register with a push provider such as FCM or APNs, enable Mobile Push in the Admin Portal, and prepare the message payload.

When the Mobile Push Notifications feature is enabled, associate device push tokens with PubNub channels. When a message is published to a channel, associated devices receive it via FCM or APNs.

For more information on sending APNs and FCM notifications, refer to iOS Mobile Push Notifications and Android Mobile Push Notifications.

PubNub doesn't know if the app is in foreground or background. Delivery depends on the published message. If it has no push payload, no push notification is sent. The server always sends data in real time. If the data includes a push payload, it triggers a push notification.

Scenario 3

Goal: display only the latest messages after a brief offline period (common in gaming).

1. Your app receives messages in real time using a listener.
2. On transition to background, your app unsubscribes from all channels.
3. On transition to foreground, your app subscribes to all the channels it unsubscribed from on transition to background.