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
}

An attestationFailure can also mean that the device reached the App Attest key limit. Its error is then HaapiErrorCode.attestationLimited (attestation_limited) and its cause a HaapiAttestationLimitRefusal, and the SDK does not fall back to Dynamic Client Registration for it. Retry no earlier than the cause’s nextAttemptAfter: the recoverySuggestion, .retryable(condition: .whenAppInForeground), carries no time. See App Attest Key Limit (iOS).

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 '@curity/identityserver-haapi-react-native-sdk'
import type { HaapiError } from '@curity/identityserver-haapi-react-native-sdk'

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

    switch (e.code) {
        case HaapiErrorCode.Communication:
        case HaapiErrorCode.DpopNonceRequired:
        case HaapiErrorCode.StorageUnavailable:
            // e.recovery?.kind === 'retryable' — retry per e.recovery.condition.
            break
        case HaapiErrorCode.AttestationFailure:
        case HaapiErrorCode.AttestationRefusedByServer:
            // 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.InvalidConfiguration:
            // e.recovery?.kind === 'unrecoverable' — fix client config.
            break
        case HaapiErrorCode.InvalidArgument:
            // A call's input can't be used — fix the call; e.errorDescription names the parameter.
            break
    }
}

HaapiError also exposes category ('bridge' | 'networking' | 'attestation' | 'dpop' | 'haapi' | 'configuration' | 'unexpected') and an optional 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.

On iOS, AttestationFailure can also mean that the device reached the App Attest key limit. That failure is retryable later — check e.recovery — and the SDK does not fall back to Dynamic Client Registration for it. See App Attest Key Limit (iOS).

Server-side HaapiResponse problems are values, not throws. Server-side authentication problems come back inside HaapiResponse as responseCategory === 'problem' — handle them in the normal flow path, not in a catch.

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.

if case .error(let error) = result,
   (error as? IdsvrError)?.error == HaapiErrorCode.nonHaapiLink.rawValue
{
    // The link target was not the configured identity server; nothing was sent.
}

A refused redirect also carries a typed cause, HaapiRedirectRefusal, with the redirect’s status code:

if case .error(let error) = result,
   let idsvrError = error as? IdsvrError,
   idsvrError.error == HaapiErrorCode.haapiRedirectRefused.rawValue,
   let refusal = idsvrError.cause as? HaapiRedirectRefusal
{
    // refusal.statusCode: the 3xx status the server answered with
}

An insecure configuration is thrown when the session is set up rather than returned in a result, so catch it where you create the accessor or HaapiManager:

do {
    let haapiAccessor = try await HaapiAccessorBuilder(haapiConfiguration: haapiConfiguration).buildForHaapi()
} catch let error as IdsvrError where error.error == HaapiErrorCode.insecureHaapiConfiguration.rawValue {
    // A configured identity-server address does not use https; nothing was sent.
    let refusal = error.cause as? HaapiInsecureConfigurationRefusal
    // refusal?.address: .baseURL, .authorizationEndpoint, .tokenEndpoint, .revocationEndpoint or .clientRegistrationEndpoint
}

Its recovery suggestion is .unrecoverable(action: .modifyConfiguration(reason:)): fix the address, do not retry. The deprecated completion-handler HaapiAccessorBuilder.build delivers the same error.

HaapiManager throws a refusal as an IdsvrHaapiException.Unrecoverable. A refused redirect carries a typed cause, HaapiRedirectRefusal, with the redirect’s status code:

try {
    val response = haapiManager.followLink(link)
} catch (e: IdsvrHaapiException) {
    when (e.error) {
        DriverErrorCodes.NON_HAAPI_LINK -> {
            // The link target was not the configured identity server; nothing was sent.
        }
        DriverErrorCodes.HAAPI_REDIRECT_REFUSED -> {
            val refusal = e.cause as? HaapiRedirectRefusal
            // refusal?.statusCode: the 3xx status the server answered with
        }
    }
}

An insecure configuration is thrown when the session is set up, so catch it where you create the accessor or HaapiManager:

try {
    val haapiAccessor = HaapiAccessorFactory(haapiConfiguration).createForHaapi()
} catch (e: IdsvrHaapiException) {
    if (e.error == DriverErrorCodes.INSECURE_HAAPI_CONFIGURATION) {
        // A configured identity-server address does not use https; nothing was sent.
        val refusal = e.cause as? HaapiInsecureConfigurationRefusal
        // refusal?.address: BASE_URL, AUTHORIZATION_ENDPOINT, TOKEN_ENDPOINT, REVOCATION_ENDPOINT or CLIENT_REGISTRATION_ENDPOINT
    }
}

Its action is UnrecoverableAction.ModifyConfiguration: fix the address, do not retry. createForOAuth() and the deprecated create() throw the same error.