CXoneChatError

public enum CXoneChatError : LocalizedError, Equatable

The different types of errors that may be experienced.

Errors when calling any method

  • The feature is not currently available for use.

    This error indicates that a feature the SDK supports could not be used because the SDK has deliberately disabled it in the current release. The associated value carries the human-readable feature name so it can be surfaced in integrator-facing error messaging and logs.

    • Source of problem: The feature is intentionally disabled in the current SDK version.

    Attention

    Wait for a new release of the SDK.

    Declaration

    Swift

    case featureUnavailable(String)

  • The SDK version being used is no longer supported.

    This error occurs when the SDK version is outdated and incompatible with the current API.

    • Source of problem: Deprecated SDK version.

    Attention

    Please upgrade to the latest version of the SDK to ensure compatibility and access to all features.

    Declaration

    Swift

    case sdkVersionNotSupported

  • An attempt was made to use a method without connecting first.

    Most of the methods in the SDK require a connection to CXone services.

    • Source of problem: SDK used incorrectly.

      Attention

      Make sure you call connect() or connect() method first.

    Declaration

    Swift

    case notConnected

  • The method being called is not supported with the current channel configuration.

    Some features are available only with multithread channel configuration.

    • Source of problem: SDK used incorrectly.

      Attention

      The channel is configured as a single-thread and called method requires a feature of multi-thread configuration, e.g. create().

    Declaration

    Swift

    case unsupportedChannelConfig

  • The conversion from object instance to data failed or when the Data object cannot be successfully converted to a valid UTF-8 string

    SDK is converting an object, like String, to the Data and vice versa and the conversion failed.

    • Source of problem: SDK/DFO issue

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case invalidData

  • The provided ID for the thread was invalid, so the action could not be performed.

    The SDK tried to find required thread but it does not exist or it is no more available.

    • Source of problem: SDK used incorrectly

    Attention

    Check if thread exists and you are providing correct thread id which reffers to threadIdOnExternalPlatform.

    Declaration

    Swift

    case invalidThread

  • There aren’t any other messages, so additional messages could not be loaded.

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case noMoreMessages

  • The provided attachment was unable to be sent.

    CXone service does not receive any/all attachments.

    • Source of problem: Unstable connection/SDK issue

    Attention

    Check if channel environment works correctly or gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case attachmentError

  • The size of the attachment exceeds the allowed size

    Channel fileRestrictions define allowed file size which can be received by the backend

    • Source of problem: SDK used incorrectly

    Attention

    Attachments should be validated for correct file size by the host application

    Declaration

    Swift

    case invalidFileSize

  • The type of the attachment is not included in the allowed file MIME type

    Channel fileRestrictions define allowed file MIME types which can be received by the backned

    • Source of problem: SDK used incorrectly

    Attention

    Attachments should be validated for correct file type by the host application

    Declaration

    Swift

    case invalidFileType

  • The server experienced an internal error and was unable to perform the action.

    SDK failed to upload attachment(s).

    • Source of problem: Unstable connection/SDK issue

    Attention

    Check if channel environment works correctly or gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case serverError

  • The parameter has not been set properly or it was unable to unwrap it as a required type.

    The SDK tried to unwrap an object but it was missing. Could be internal object or data from the server.

    • Source of problem: DFO issue/SDK issue

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case missingParameter(String)

  • A invalid parameter has been passed to a method call.

    This is one of:

    • send(_:) was called with no valid postback, empty text, and no attachments.

    Declaration

    Swift

    case invalidParameter(String)

  • The brand has configured pre-chat survey with contact custom fields which needs to be provided via create(with:) method.

    • Source of problem: SDK used incorrectly

    Attention

    Fill-up custom fields available in the preChatSurvey and pass them as a parameter in the create(with:) method.

    Declaration

    Swift

    case missingPreChatCustomFields

  • A provided custom field does not have a definition in the case custom fields.

    CXone service handles only those custom fields that are configured in the brand settings and others are ignored.

    • Source of problem: SDK used incorrectly

    Attention

    Check the contact custom fields configured in your brand settings or the fields offered by preChatSurvey.

    Declaration

    Swift

    case unknownCaseCustomFields

  • A provided custom field does not have a definition in the customer custom fields.

    CXone service handles only those custom fields that are configured in the brand settings and others are ignored.

    • Source of problem: SDK used incorrectly

    Attention

    Check the customer custom fields configured in your brand settings.

    Declaration

    Swift

    case unknownCustomerCustomFields

  • The SDK instance could not get customer identity possibly because it may not have been set.

    Customer identity is necessary for binding threads to the visitor.

    • Source of problem: SDK used incorrectly/SDK issue

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case customerAssociationFailure

  • The SDK tried to send a transcript but something went wrong

    • Source of problem: SDK used incorrectly/BE issue

    Attention

    Check if the feature is enabled via isSendTranscriptEnabled and the provided e-mail is valid. Otherwise, gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case sendTranscriptFailed

Errors when calling connect

  • The WebSocket refused to connect.

    This error may occur within connection establishing process and it can relate to several issues - wrong IDs, an internet or CXone service connectivity issue or wrong connection URL.

    • Source of problem: SDK used incorrectly/DFO issue

    Attention

    Check entered BrandID and ChannelID. If you are providing your own chatURL or socketURL, double check that these URLs are correct. Otherwise, Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case webSocketConnectionFailure

  • The channel configuration could not be retrieved.

    This error may occur with getting channel configuration and it can relate to several issues - wrong IDs or wrong connection URL.

    • Source of problem: SDK used incorrectly

    Attention

    Check entered BrandID and ChannelID. If you are providing your own chatURL or socketURL, double check that these URLs are correct.

    Declaration

    Swift

    case channelConfigFailure

  • The customer was successfully authorized, but an access token wasn’t returned.

    The access token is used in case of OAuth authorization process.

    • Source of problem: DFO issue

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case missingAccessToken

  • The customer could not be associated with a visitor.

    Some events, except customer identity, uses visitorId to match an user.

    • Source of problem: SDK issue

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case customerVisitorAssociationFailure

  • The connection request was invalid and couldn’t be completed.

    connect() may throw this error in case of incorrectly set socket endpoint object.

    • Source of problem: SDK used incorrectly/SDK issue

    Attention

    Check entered IDs and URLs. Otherwise, gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case invalidRequest

  • Thread is missing the timestamp of when the message was created.

    Every thread message contains timestamp to be able to identify latest message for loading previously created and not yet loaded messages via loadMoreMessages() method.

    • Source of problem: DFO issue

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case invalidOldestDate

  • An attached file could not be found.

    It has been stored in an unknown location or its location is not accessible from the secure scope and it is not handled.

    • Source of problem: SDK used incorrectly/SDK issue

    Attention

    Store your attachment in the secured scope or in the application documents directory. Otherwise, gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case noSuchFile(String)

  • An analytics event has been generated when no visit was available.

    Attention

    viewPage(title:url:) must be called before any other analytics events are generated

    Declaration

    Swift

    case missingVisitId

  • connect() or an analytics event has been generated when no visitor id was available.

    Attention

    prepare(environment:brandId:channelId:) or prepare(chatURL:socketURL:loggerURL:brandId:channelId:tokenURL:) must be called before connect() or any other analytics events are generated.

    Declaration

    Swift

    case missingVisitorId

  • Unable to trigger the required method because the SDK is not in the required state.

    The SDK has to be in correct state to trigger required operation. For example, connecting to the CXone service for chatting with an agent, it is firstly necessary to prepare(environment:brandId:channelId:) channel configuration which leads to the prepared state and then it’s possible to connect() to the websocket.

    Check ChatState for more information.

    Source of problem

    SDK used incorrectly

    Declaration

    Swift

    case illegalChatState

  • Unable to trigger the required method because the chat thread is not in the required state.

    The chat thread has to be in correct state to trigger required operation. For example, to update thread name via updateName(_:) the thread can not be in closed state.

    Check ChatThreadState for more information.

    Source of problem

    SDK used incorrectly

    Declaration

    Swift

    case illegalThreadState

  • Did not receive a paired response from the server in the expected time.

    The SDK sent a request event to the server, but the server did not respond in the expected time.

    • Source of problem: SDK issue, DFO issue

    Attention

    Gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case eventTimeout

Errors when using transaction token authentication

  • The transaction token request failed.

    This error occurs when the SDK is unable to obtain a transaction token from the server. The token is required for WebSocket authentication when using secured cookie or third-party OAuth authentication modes.

    • Source of problem: Network issue/Server issue/SDK issue

    Attention

    Check network connectivity and ensure the channel is properly configured for transaction token authentication. Otherwise, gather any information about how the error was encountered and contact the CXoneChat SDK team.

    Declaration

    Swift

    case transactionTokenRequestFailed(statusCode: Int)

    Parameters

    statusCode

    The HTTP status code returned by the server.

Errors related to OAuth token handling

  • The provided access token is invalid.

    This error occurs when the token supplied via setConnectionToken(_:expiresAt:) is empty, expired, or rejected by the backend.

    • Source of problem: SDK used incorrectly / OAuth provider issue

    Attention

    Obtain a fresh token from your OAuth provider and supply it to the SDK.

    Declaration

    Swift

    case invalidAccessToken

  • The session’s refresh token could not be used to recover the session automatically — it was rejected by the backend, was never stored, or the refresh grant returned no new access token.

    This error occurs when a refresh-grant recovery attempt for the explicit OAuth flow cannot succeed and no further automatic recovery is possible.

    • Source of problem: OAuth provider issue / refresh token revoked or expired

    Attention

    The app owns re-authentication in this case — perform a new authorization-code (PKCE) grant to obtain a fresh access + refresh token pair, then supply it to the SDK.

    Declaration

    Swift

    case invalidRefreshToken(String?)

    Parameters

    message

    The backend’s own description of the rejection, when it supplied one. It is a fixed string tied to the backend’s error code rather than text from the OAuth provider, so it is useful for diagnostics and logging but should not be parsed or branched on. nil when the session could not be recovered without the backend rejecting anything — no refresh token was stored, or a successful response arrived without a new access token.

Properties

  • Declaration

    Swift

    public var errorDescription: String? { get }

Methods

  • Declaration

    Swift

    public static func == (lhs: `Self`, rhs: `Self`) -> Bool