Error Handling

This section helps with handling Offline Navigation failures with stable error codes instead of diagnostic message text and converting callback errors, choosing safe retry behavior, and initiating recovery after checking current state, network policy, storage, and lifecycle ownership.

Normally, NBNavigation reports failures through NBNavigationApiException. Convert any callback “Throwable” with toNavigationError(), branch on the stable NBNavigationErrorCode enum, and retain causeCode for diagnostics. Do not use message or causeDescription as a business-logic condition.

1
private fun recoveryMessage(throwable: Throwable): String {
2
    val error = NBNavigation.toNavigationError(throwable)
3
    return when (error.code) {
4
        NBNavigationErrorCode.INVALID_ARGUMENT ->
5
            "Check the request parameters; do not retry unchanged input."
6
        NBNavigationErrorCode.NETWORK_UNAVAILABLE ->
7
            "Wait until the configured network policy is satisfied."
8
        NBNavigationErrorCode.TIMEOUT ->
9
            "Retry with bounded exponential backoff."
10
        NBNavigationErrorCode.OFFLINE_DATA_NOT_READY,
11
        NBNavigationErrorCode.OFFLINE_DATA_VERSION_MISMATCH ->
12
            "Synchronize the catalog and download or update the required regions."
13
        NBNavigationErrorCode.INTERRUPTED ->
14
            "Refresh actual state; retry only if the user still wants the operation."
15
        NBNavigationErrorCode.OFFLINE_REGION_ALREADY_ACTIVE,
16
        NBNavigationErrorCode.OFFLINE_REGION_NOT_DOWNLOADING,
17
        NBNavigationErrorCode.OFFLINE_REGION_NOT_PAUSED,
18
        NBNavigationErrorCode.OFFLINE_REGION_INVALID_STATE ->
19
            "Refresh observed progress before choosing the next control action."
20
        else -> if (error.recoverable) {
21
            "Retry a limited number of times after checking network and storage."
22
        } else {
23
            "Stop automatic retry and report code=${error.code}, cause=${error.causeCode}."
24
        }
25
    }
26
}

Stable code	Retry policy	Recommended user or application action
`INVALID_ARGUMENT`	No	Correct the request before trying again
`ENGINE_NOT_INITIALIZED` / `OFFLINE_SDK_NOT_REGISTERED`	After initialization	Initialize Maps and NBNavigation, then retry once
`NETWORK_UNAVAILABLE`	When connectivity returns	Check WIFI_ONLY, UNMETERED, or ANY and wait for a matching network
`TIMEOUT`	Bounded	Use exponential backoff and stop when the owning screen or request is no longer active
`OFFLINE_DATA_NOT_READY`	After data changes	Download every route region required by the trip
`OFFLINE_DATA_VERSION_MISMATCH`	After update	Synchronize catalogs and update the affected region
`INTERRUPTED`	User dependent	Refresh actual progress; do not restart work the user cancelled
`OFFLINE_REGION_NOT_FOUND`	No unchanged retry	Refresh catalogs and verify regionId
`OFFLINE_REGION_ALREADY_ACTIVE`	No immediate retry	Keep observing the existing task
`OFFLINE_REGION_NOT_DOWNLOADING` / `NOT_PAUSED` / `INVALID_STATE`	After state refresh	Choose an action that matches current progress
`OFFLINE_REGION_DELETE_FAILED` / `CANCEL_FAILED`	Bounded	Refresh both subsystems and retry only the incomplete operation
`EXECUTION_FAILED` / `INTERNAL_ERROR` / `UNKNOWN`	Bounded if recoverable	Capture code, causeCode, SDK version, and engine version for support

A recoverable value means that restoring connectivity, freeing storage, or retrying a limited number of times may resolve the failure. It does not authorize indefinite retries. Recheck network policy, available storage, and lifecycle ownership before each retry. Use healthCheck(callback) only to inspect local engine and data health and should not be used to replace the routeNetwork and mapTile completion checks.