Handle Structured Errors

This section deals with converting SDK failures into structured OfflineRegionError values and use stable error codes for localized messages, logging, and diagnostics. Regional Offline suspend APIs use Result to return errors. First convert the throwable to OfflineRegionError, then handle it by subtype or stable errorCode:

1
private fun renderError(throwable: Throwable) {
2
    val error = OfflineRegionError.from(throwable)
3
    when (error) {
4
        is OfflineRegionError.Network ->
5
            showLocalizedMessage(R.string.offline_network_error)
6
        is OfflineRegionError.Storage ->
7
            showLocalizedMessage(R.string.offline_storage_error)
8
        is OfflineRegionError.StyleNotCached ->
9
            showLocalizedMessage(R.string.offline_resources_not_ready)
10
        is OfflineRegionError.NoInstalledRegions ->
11
            showLocalizedMessage(R.string.offline_no_installed_region)
12
        is OfflineRegionError.NotInitialized ->
13
            showLocalizedMessage(R.string.offline_not_initialized)
14
        is OfflineRegionError.UnsupportedTileServer ->
15
            showLocalizedMessage(R.string.offline_tomtom_required)
16
        is OfflineRegionError.Unknown ->
17
            showLocalizedMessage(R.string.offline_unknown_error)
18
    }
19

20
    logOfflineFailure(error.errorCode, error)
21
}

Stable error codes:

Type	errorCode
StyleNotCached	`STYLE_NOT_CACHED`
NoInstalledRegions	`NO_INSTALLED_REGIONS`
Storage	`STORAGE`
Network	`NETWORK`
Unknown	`UNKNOWN`
NotInitialized	`NOT_INITIALIZED`
UnsupportedTileServer	`UNSUPPORTED_TILE_SERVER`

message and the download progress field errorMessage are diagnostic text. They are not machine-readable protocols and must not be displayed directly as user-facing copy.