9. Download Error Codes

The iOS SDK notifies the application layer of exceptions by combining the code property and localizedDescription message of an NSError instance.

---

SDK error codes

The following are the main error codes classified by (error as NSError).code and their trigger points.

Error type	Description	Trigger
Authentication error	SDK key expired or invalid key	At start() or startWithCheck()
Unsupported device	Device does not support SDK or DRM	At start() or when DRM compatibility validation fails
Insufficient storage	Insufficient disk space	At the start of metadata loading (load) and file download (download)
File write failure	File write error	When a disk I/O error occurs during download
Duplicate download	Duplicate download request	When downloadContent(mck) is called for the same content
Download already complete	Content already downloaded	When downloadContent(mck) is called for already downloaded content
Content not found	Target file not found	At content removal (removeContent) or validation (checkContentURL)
Expiration date exceeded	DRM expiration date exceeded	When attempting offline playback
Playback time exceeded	DRM remaining playback time exceeded (remaining time is 0)	When attempting offline playback
Playback count exceeded	DRM remaining playback count exceeded (remaining count is 0)	When attempting offline playback
DRM forced deletion	Content forcibly deleted by DRM callback kind2 or kind3 response	When a response is detected in the delegate callback (request:json:error:) parameters

Development guidelines

The detailed types of integer code values (code) emitted by the SDK match the ErrorCodes structure of the Android SDK. However, in the iOS development environment, it is recommended to handle exceptions by branching on NSError.code, and to map specific text to the screen using the localizedDescription property.

Error handling example

do {
    try storage.start()
} catch {
    let nsError = error as NSError
    UIApplication.presentErrorViewController(
        title: "Error Code: \(nsError.code)",
        errorDescription: nil,
        errorReason: error.localizedDescription
    )
}

---

External errors

These are response patterns for errors that may occur due to mobile operating system policies or network errors, outside of the SDK's internal logic.

• Insufficient disk space: It is recommended to call DiskStatus.freeDiskSpaceInBytes before starting a download to check available capacity.
• Network connection failure: The SDK automatically retries. The automatic retry threshold can be adjusted with storage.setNetworkTimeOut(timeOut:retry:), and the setting storage.setNetworkTimeOut(timeOut: 30, retry: 3) is recommended.
• Background force termination: To prevent transfers from being cancelled by the operating system when the app moves to the background, it is recommended to enable the setBackgroundDownload(true) setting and review the UIBackgroundModes spec in Info.plist.

---

Recommended user messages by error type

Error type	Example user message
Authentication error	"There is a problem with app authentication. Please update the app to the latest version."
Insufficient storage	"Your device does not have enough storage space. Please delete downloaded files you have finished watching or free up storage space."
File write failure	"Failed to save the file. Please try again later."
Expiration error	"The content viewing period has expired. Please connect to a network to renew the license."
Unsupported device	"Content cannot be downloaded or played on this device."