Error Handling (SDK Layer)#

Completion handlers surface Error values. Cast to HaapiError for the enum, then consult recoverySuggestion for retry guidance:

private func handleError(_ error: Error) {
    guard let haapiError = error as? HaapiError else { return }
    switch haapiError.recoverySuggestion {
    case .retryable(let condition):
        // condition is .now (retry immediately with exponential backoff)
        // or .whenAppForeground (defer until the app is foregrounded)
        break
    case .newHaapiFlow:
        // start a fresh HAAPI flow
        break
    case .nonRecoverable(let action):
        // action is .modifyConfiguration (developer to fix client settings),
        // .invalidPlatform (device cannot satisfy the protocol),
        // or .introspectCause (inspect the wrapped cause for follow-up)
        break
    }
}

Specific HaapiError cases — attestationFailure, haapiTokenManagerIsClosed, invalidStatusCode, serverError, dpopKeyCreationFailure, dpopProofFailure — can be matched directly when their context matters:

switch haapiError {
case .attestationFailure(let cause):
    // attestation rejected — surface to user; consider DCR fallback
    break
case .haapiTokenManagerIsClosed:
    // construct a new manager and start over
    break
case .dpopKeyCreationFailure, .dpopProofFailure:
    // rare; rebuild configuration with .p256 and re-authenticate
    break
default:
    break
}

HaapiManager and OAuthTokenManager throw IdsvrHaapiException. The SDK performs a single automatic retry on transport-level retryable conditions before propagating:

try {
    val response = haapiManager.start(coroutineContext)
    handleHaapiResponse(response)
} catch (e: IdsvrHaapiException.Retryable) {
    // e.condition is Now (retry immediately) or WhenAppForeground (defer)
} catch (e: IdsvrHaapiException.Unrecoverable) {
    // e.action is ModifyConfiguration, InvalidPlatform, or IntrospectCause
}

Retryable subtypes include HttpClientRetryableException.SocketStreamInterruptionException, HostConnectionException, HttpRetryException (408, 429, 5xx with Retry-After), and HaapiRetryableException.UseDpopNonceException. Unrecoverable subtypes include AccessDeniedException, UnsupportedDeviceException, and UnsupportedConfigurationException.

When HttpClient.Response.Failure has a response code of 0, the failure is internal (parsing, attestation, key generation) rather than a server response.

Every SDK failure rejects the Promise with a typed HaapiError. Catch it with try/catch and narrow with isHaapiError(e), then branch on the stable error.code:

import { isHaapiError, HaapiErrorCode } from 'identityserver.haapi.reactnative.sdk'
import type { HaapiError } from 'identityserver.haapi.reactnative.sdk'

try {
    const response = await accessor.haapiManager.start()
    // …
} catch (e) {
    if (!isHaapiError(e)) throw e

    switch (e.code) {
        case HaapiErrorCode.Networking:
        case HaapiErrorCode.DPoP:
            // e.recovery.kind === 'retryable' — retry per e.recovery.condition.
            break
        case HaapiErrorCode.Attestation:
            // Attestation rejected — surface to user; consider DCR fallback.
            break
        case HaapiErrorCode.AccessorAlreadyInitialized:
        case HaapiErrorCode.AccessorNotInitialized:
            // Lifecycle misuse — close any held accessor and re-initialise.
            break
        case HaapiErrorCode.Configuration:
            // e.recovery.kind === 'unrecoverable' — fix client config.
            break
    }
}

HaapiError also exposes category ('bridge' | 'networking' | 'attestation' | 'dpop' | 'haapi' | 'config' | 'unexpected') and recovery: { kind: 'retryable' | 'newHaapiFlow' | 'unrecoverable', condition?, action? } for the higher-level branching pattern. For HAAPI server errors, e.serverError carries the parsed RFC 7807 payload.

switch tokenResponse {
case let .successfulToken(success):
    // persist tokens
    break
case let .errorToken(errorResponse):
    // errorResponse.error and errorResponse.errorDescription
    break
case let .error(anError):
    // framework or transport error — see Retryable / Unrecoverable above
    break
}

when (tokenResponse) {
    is SuccessfulTokenResponse -> {
        // persist tokens
    }
    is ErrorTokenResponse -> {
        tokenResponse.error              // "invalid_grant", "invalid_dpop_proof", etc.
        tokenResponse.errorDescription
    }
}

if (tokenResponse.responseType === 'success') {
    // persist tokens
} else {
    tokenResponse.error             // "invalid_grant", "invalid_dpop_proof", etc.
    tokenResponse.errorDescription
    tokenResponse.errorUri
}

OAuth-protocol errors resolve the Promise — they don’t throw. The try/catch block above only fires for transport / attestation / DPoP / bridge failures.