---
source_url: https://www.pubnub.com/docs/sdks/cocoa-swift/status-events
title: Status Events for Cocoa Swift SDK
updated_at: 2026-05-21T15:46:25.084Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Status Events for Cocoa Swift SDK

This SDK has been replaced by a new PubNub Swift SDK written purely in Swift. Check out the Swift SDK page [PubNub Swift SDK documentation](https://www.pubnub.com/docs/sdks/swift).

There is set of error categories which is returned by PubNub client through API completion blocks or delegate callbacks. Access to category can be done using status category property.

Delegate callbacks related to subscribe API usage and allow to handle real-time updates and errors.

:::note Target listener
To handle events, target listener should conform to `PNObjectEventListener` protocol and register as listener using the `addListener` PubNub client instance method.
:::

* [PNAccessDeniedCategory](#pnaccessdeniedcategory)
* [PNTimeoutCategory](#pntimeoutcategory)
* [PNNetworkIssuesCategory](#pnnetworkissuescategory)
* [PNUnexpectedDisconnectCategory](#pnunexpecteddisconnectcategory)
* [PNBadRequestCategory](#pnbadrequestcategory)
* [PNMalformedFilterExpressionCategory](#pnmalformedfilterexpressioncategory)
* [PNMalformedResponseCategory](#pnmalformedresponsecategory)
* [PNDecryptionErrorCategory](#pndecryptionerrorcategory)
* [PNTLSConnectionFailedCategory](#pntlsconnectionfailedcategory)
* [PNTLSUntrustedCertificateCategory](#pntlsuntrustedcertificatecategory)

## PNAccessDeniedCategory

**API:** Subscribe, Publish, History, Presence, State, Stream controller, APNS.

**Description:** **PubNub** Access Manager forbidden access to particular API.

**Reason:** At the moment when API has been used, access rights hasn't been applied to the client with specified authKey yet.

**Handle strategy:** Retry API call few times using provided retry method. If `willAutomaticallyRetry` is set to **YES** there will be no need to call retry method.

It is possible, what access has been revoked and some retry counter should be used to ensure what retry process won't least forever.

:::note Automatic retry functionality
At this moment only `subscribe` API provide automatic retry functionality. Rest API calls explicitly should retry calling retry method which is provided by `PNStatus` subclass instance.
:::

### Delegate callbacks

This is the only API which in case of error access error automatically will retry subscription.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNAccessDeniedCategory {

        let errorStatus: PNErrorStatus = status as! PNErrorStatus
        // List of channels for which Access Manager reported access error.
        let channels: Array<String> = errorStatus.errorData.channels
        // List of channel groups for which Access Manager reported access error.
        let groups: Array<String> = errorStatus.errorData.channelGroups

        // Stop automatic retry if required.
        if status.willAutomaticallyRetry && self.shouldStopAutoRetry() {

            status.cancelAutomaticRetry()
        }
    }
}
```

### Completion blocks

Depending from used api, completion block may pass only `PNStatus` or both: `PNResult` and `PNStatus` subclass instances. For simplification handling code will be demonstrated only for completion block which pass only `PNStatus` subclass instance.

```swift
var retryCount: UInt = 0
let maxRetry: UInt = 3
{ (status) in

    if status.category == .PNAccessDeniedCategory {

        if retryCount + 1 < maxRetry {
            retryCount += 1
            status.retry()
        }
        else {
            // Report access rights error.
        }
    }
})
```

## PNTimeoutCategory

**API:** Subscribe, Publish, History, Presence, State, Stream controller, APNS.

**Description:** API processing failed because of request time out.

**Reason:** Slow connection when request doesn't have enough time to complete processing (send request body and receive server response).

**Handle strategy:** Retry API call few times using provided retry method. If `willAutomaticallyRetry` is set to **YES** there will be no need to call retry method.

:::note Automatic retry functionality
At this moment only `subscribe` API provide automatic retry functionality. Rest API calls explicitly should retry calling retry method which is provided by `PNStatus` subclass instance.
:::

### Delegate callbacks

Event listeners will receive this kind of error as `PNUnexpectedDisconnectCategory`. Last API call will be retried in case if `subscribe` API has been used.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNUnexpectedDisconnectCategory {

        // Stop automatic retry if required.
        if status.willAutomaticallyRetry && self.shouldStopAutoRetry() {

            status.cancelAutomaticRetry()
        }
    }
}
```

### Completion blocks

Depending from used api, completion block may pass only `PNStatus` or both: `PNResult` and `PNStatus` subclass instances. For simplification handling code will be demonstrated only for completion block which pass only `PNStatus` subclass instance.

```swift
var retryCount: UInt = 0
let maxRetry: UInt = 3
{ (status) in

    if status.category == .PNTimeoutCategory {

        if retryCount + 1 < maxRetry {
            retryCount += 1
            status.retry()
        }
        else {

            // Report potential network issues.
        }
    }
})
```

## PNNetworkIssuesCategory

**API:** Subscribe, Publish, History, Presence, State, Stream controller, APNS.

**Description:** API request is impossible because there is no connection.

**Reason:** No active connection to the Internet.

**Handle strategy:** Check for network connectivity and retry API call later when internet connection will be restored.

### Delegate callbacks

Event listeners will receive this kind of error as `PNUnexpectedDisconnectCategory`. In case of network issues **PubNub** client use periodic call to time API to check when network connection will be restored.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNUnexpectedDisconnectCategory {

        // Report 'offline' state.
        // Wait for automatic connection completion or use any
        // reachability API to be notified about network connection
        // restoring.
        // Retry API call on network connection restore (in case of manual
        // network discovery).
    }
}
```

### Completion blocks

```swift
{ (status) in

    if status.category == .PNNetworkIssuesCategory {

        // Report operation failure.
         // For automated (not by user request) any reachability API
         // should be used to be notified about network connection restore.
         // Retry API call (on user request or on network connection detection).
    }
})
```

## PNUnexpectedDisconnectCategory

**API:** Subscribe.

**Description:** Status sent when client unexpectedly lost ability to receive live updates from **PubNub** service (this status object's error flags is set to **NO**.

**Reason:** Initial or long-poll request failed because of following reasons: [timeout](#pntimeoutcategory), [malformed service response](#pnmalformedresponsecategory), or *secure connection handshake error*.

**Handle strategy:** Retry API call few times using provided retry method. If `willAutomaticallyRetry` is set to **YES** there will be no need to call retry method.

_ [Malformed service response](#pnmalformedresponsecategory) - SDK expect properly formatted JSON objects from **PubNub** service. This may happen when you connect to a public WiFi Hotspot that requires you to auth via your web browser first, or if there is a proxy somewhere returning an HTML access denied error, or if there was an intermittent server issue.

### Delegate callbacks

Event listeners will receive this kind of error as `PNUnexpectedDisconnectCategory`. Last API call will be retried in case if `subscribe` API has been used.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNUnexpectedDisconnectCategory {

        // Stop automatic retry if required.
        if status.willAutomaticallyRetry && self.shouldStopAutoRetry() {

            status.cancelAutomaticRetry()
        }
    }
}
```

## PNBadRequestCategory

**API:** Subscribe, Publish, History, Presence, State, Stream controller, APNS.

**Description:** Status is used to notify what API request from client is malformed.

**Reason:** This type of status is possible in case if wrong data type or content has been passed to API.

**Handle strategy:** Ensure what empty publish/subscribe keys not used during **PubNub** client instantiation. Check values passed to API and verify whether their data type and content correspond to expected values (using documentation and IDE warnings).

### Delegate callbacks

Event listeners will receive this kind of error as `PNUnexpectedDisconnectCategory`. Last API call will be retried in case if `subscribe` API has been used.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNUnexpectedDisconnectCategory {

        // If this is initial subscription after client initialization
        // assertion will be good here to catch potential issues before
        // they will be pushed to production.
    }
}
```

### Completion blocks

```swift
{ (status) in

    if status.category == .PNBadRequestCategory {

        // Assertion will be good here to catch potential issues before they
        // will be pushed to production.
    }
})
```

## PNMalformedFilterExpressionCategory

**API:** Subscribe.

**Description:** Status is used to notify what client has been configured with malformed filtering expression.

**Reason:** In case if this status arrive, check syntax used for `filterExpression` property.

**Handle strategy:** Please use message filtering documentation to validate used expression. Check what all used single/double quotes paired and escaped if required.

### Delegate callbacks

In case of this kind of error `subscribe` request automatic retry disabled.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNMalformedFilterExpressionCategory {

        // Assertion will be good here to catch potential issues before they
        // will be pushed to production.
    }
}
```

## PNMalformedResponseCategory

**API:** Subscribe, Publish, History, Presence, State, Stream controller, APNS.

**Description:** **PubNub** because of some issues sent malformed response.

**Reason:** This may happen when you connect to a public WiFi Hotspot that requires you to auth via your web browser first, or if there is a proxy somewhere returning an HTML access denied error, or if there was an intermittent server issue.

**Handle strategy:** Retry API call few times using provided *retry* method. If `willAutomaticallyRetry` is set to **YES** there will be no need to call *retry* method.

:::note Automatic retry functionality
At this moment only `subscribe` API provide automatic retry functionality. Rest API calls explicitly should retry calling retry method which is provided by `PNStatus` subclass instance.
:::

### Delegate callbacks

Event listeners will receive this kind of error as `PNUnexpectedDisconnectCategory`. Last API call will be retried in case if `subscribe` API has been used.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNUnexpectedDisconnectCategory {

        // Stop automatic retry if required.
        if status.willAutomaticallyRetry && self.shouldStopAutoRetry() {

            status.cancelAutomaticRetry()
        }
    }
}
```

### Completion blocks

Depending from used api, completion block may pass only `PNStatus` or both: `PNResult` and `PNStatus` subclass instances. For simplification handling code will be demonstrated only for completion block which pass only `PNStatus` subclass instance.

```swift
var retryCount: UInt = 0
let maxRetry: UInt = 3
{ (status) in

    if status.category == .PNMalformedResponseCategory {

        if retryCount + 1 < maxRetry {
            retryCount += 1
            status.retry()
        }
        else {

            // Report request processing error.
        }
    }
})
```

## PNDecryptionErrorCategory

**API:** Subscribe, History.

**Description:** **PubNub** client can't use provided `cipherKey` to decrypt received message.

**Reason:** **PubNub** client configured with different `cipherKey` then *key* which has been used to encrypt message. **PubNub** client configured with `cipherKey` but unencrypted message has been received.

### Delegate callbacks

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNDecryptionErrorCategory {

        let errorStatus: PNErrorStatus = status as! PNErrorStatus
        let data: PNMessageData = errorStatus.associatedObject as! PNMessageData
        // Reference on channel on which message has been received.
        let channel: String = data.channel
        // Reference on message which SDK was unable to decrypt.
        let message: Any? = data.message

        // Use PNAES.decrypt(_:withKey:) to decrypt with custom key
        // or handle message as-is.
    }
}
```

### Completion blocks

Depending from used api, completion block may pass only `PNStatus` or both: `PNResult` and `PNStatus` subclass instances. For simplification handling code will be demonstrated only for completion block which pass only `PNStatus` subclass instance.

```swift
self.client.historyForChannel("history_channel", withCompletion: { (result, status) in

    if status != nil && status.category == .PNDecryptionErrorCategory {

        let errorStatus: PNErrorStatus = status as! PNErrorStatus
        let data: PNHistoryData = errorStatus.associatedObject as! PNHistoryData
        // Reference on received list of messages.
        let messages = data.messages;

        // Use PNAES.decrypt(_:withKey:) to decrypt each message with custom
        // key or handle message as-is.
    }
})
```

## PNTLSConnectionFailedCategory

**API:** Subscribe, Publish, History, Presence, State, Stream controller, APNS.

**Description:** Status is sent in case if client was unable to use API using secured connection.

**Reason:** Secured connection handshake did fail because of: certificate issues or handshake process issues because of too slow connection or too big packets loss.

**Handle strategy:** Retry API call few times using provided *retry* method. If `willAutomaticallyRetry` is set to **YES** there will be no need to call *retry* method.

:::note Automatic retry functionality
At this moment only `subscribe` API provide automatic retry functionality. Rest API calls explicitly should retry calling retry method which is provided by `PNStatus` subclass instance.
:::

### Delegate callbacks

Event listeners will receive this kind of error as `PNUnexpectedDisconnectCategory`. Last API call will be retried in case if `subscribe` API has been used.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNUnexpectedDisconnectCategory {

        // Stop automatic retry if required.
        if status.willAutomaticallyRetry && self.shouldStopAutoRetry() {

            status.cancelAutomaticRetry()
        }
    }
}
```

### Completion blocks

Depending from used api, completion block may pass only `PNStatus` or both: `PNResult` and `PNStatus` subclass instances. For simplification handling code will be demonstrated only for completion block which pass only `PNStatus` subclass instance.

```swift
var retryCount: UInt = 0
let maxRetry: UInt = 3
{ (status) in

    if status.category == .PNTLSConnectionFailedCategory {

        if retryCount + 1 < maxRetry {
            retryCount += 1
            status.retry()
        }
        else {

            // Report request processing error.
        }
    }
})
```

## PNTLSUntrustedCertificateCategory

**API:** Subscribe, Publish, History, Presence, State, Stream controller, APNS.

**Description:** Status is sent in case if client unable to check certificates trust chain.

**Reason:** Secured connection handshake did fail because of proxy or VPN which has been used to connect to internet.

**Handle strategy:** Retry API call few times using provided retry method. If `willAutomaticallyRetry` is set to **YES** there will be no need to call retry method.

:::note Automatic retry functionality
At this moment only `subscribe` API provide automatic retry functionality. Rest API calls explicitly should retry calling retry method which is provided by `PNStatus` subclass instance.
:::

### Delegate callbacks

Event listeners will receive this kind of error as `PNUnexpectedDisconnectCategory`. Last API call will be retried in case if `subscribe` API has been used.

```swift
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.category == .PNUnexpectedDisconnectCategory {

        // Stop automatic retry if required.
        if status.willAutomaticallyRetry && self.shouldStopAutoRetry() {

            status.cancelAutomaticRetry()
        }
    }
}
```

### Completion blocks

Depending from used api, completion block may pass only `PNStatus` or both: `PNResult` and `PNStatus` subclass instances. For simplification handling code will be demonstrated only for completion block which pass only `PNStatus` subclass instance.

```swift
var retryCount: UInt = 0
let maxRetry: UInt = 3
{ (status) in

    if status.category == .PNTLSUntrustedCertificateCategory {

        if retryCount + 1 < maxRetry {
            retryCount += 1
            status.retry()
        }
        else {

            // Report request processing error.
        }
    }
})
```