Handle Structured Errors

This guide covers how to deal with structured errors encountered while downloading offline map packages. Offline Maps operations can report errors through the downloadRegion completion handler before a task is accepted, and through progress.error after a task has been enqueued.

Since, in Swift, progress.error is exposed as Error?. Cast it to NSError to read the Offline Maps error domain, code, and diagnostic userInfo values.

1
func handleRegionalOfflineError(_ error: Error?) {
2
guard let error else { return }
3
4
let nsError = error as NSError
5
6
guard nsError.domain == NGLRegionalOfflineErrorDomain else {
7
print("Unexpected error: \(nsError)")
8
return
9
}
10
11
let code = NGLRegionalOfflineError.Code(rawValue: nsError.code)
12
13
switch code {
14
case .networkUnavailable:
15
// Ask the user to check the network connection.
16
break
17
18
case .requestTimedOut:
19
// Offer a retry action.
20
break
21
22
case .httpStatus:
23
let statusCode =
24
nsError.userInfo[NGLRegionalOfflineErrorHTTPStatusCodeKey] as? Int
25
print("HTTP status: \(statusCode ?? 0)")
26
27
case .insufficientStorage:
28
// Ask the user to free device storage.
29
break
30
case .unsupportedTileServer:
31
// Switch NGLAccountManager to NGLTomTom before using Regional Offline.
32
break
33
34
case .invalidPackage, .packageDecompression, .packageInstallation:
35
// Retry the download and report persistent package failures.
36
break
37
38
default:
39
break
40
}
41
42
let requestURL =
43
nsError.userInfo[NGLRegionalOfflineErrorURLKey] as? String
44
let packageName =
45
nsError.userInfo[NGLRegionalOfflineErrorPackageNameKey] as? String
46
47
print(
48
"Regional offline failed: " +
49
"domain=\(nsError.domain) " +
50
"code=\(nsError.code) " +
51
"package=\(packageName ?? "-") " +
52
"url=\(requestURL ?? "-") " +
53
"message=\(nsError.localizedDescription)"
54
)
55
}

Following is the table with references for errors:

Swift error codeMeaningRecommended action
.networkUnclassified network errorCheck connectivity and retry
.networkUnavailableNo connection, DNS failure, or host connection failureWait for connectivity
.requestTimedOutRequest timed outOffer retry
.httpStatusNon-2xx HTTP responseRecord the HTTP status and verify the service
.invalidResponseInvalid catalog or region responseVerify server data
.storageGeneric storage errorCheck device storage
.fileSystemFile create, read, or write failureCheck storage and retry
.insufficientStorageInsufficient free storageAsk the user to free space
.invalidPackageCorrupt or unsupported packageRetry or verify the server package
.packageDecompressionPackage decompression failedRetry the download
.packageInstallationPackage installation failedCheck storage and retry
.invalidRegionInvalid or unknown regionRefresh the catalog
.previewNotReadyShared preview resources are not readyWait for resource preparation
.styleNotCachedThe offline style is not cachedUse an SDK offline style and prepare preview resources
.noInstalledRegionsNo installed region is availableAsk the user to download a region
.cancelledDownload was cancelled or pausedResume according to the product flow
.unknownUnclassified or legacy errorRecord the complete error
.downloadAlreadyActiveThe same region already has an active taskReuse, wait for, cancel, or delete the existing task
.previewDatabaseOpenThe native engine could not open the validated Preview databaseKeep the task incomplete and record the database path and underlying error
.previewRollbackFailedPreview activation failed and rollback was incompleteStop completion and record the rollback error array
.unsupportedTileServerThe active tile server has no supported Regional Offline packagesSelect NGLTomTom before configuring or using Regional Offline