Error Handling (Driver 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):
        // schedule a retry based on the condition
        break
    case .newHaapiFlow:
        // start a fresh HAAPI flow
        break
    case .nonRecoverable(let action):
        // surface the cause to the user; no retry possible
        break
    }
}

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

switch haapiError {
case .attestationFailure(let cause):
    // attestation rejected — surface to user, do not auto-retry
    break
case .haapiTokenManagerIsClosed:
    // construct a new manager and start over
    break
case .invalidStatusCode(let statusCode):
    // server returned an unexpected status
    break
default:
    break
}

The driver throws IdsvrHaapiException, split into two main categories:

try {
    val result = throwableOperation()
} catch (e: IdsvrHaapiException.Retryable) {
    // transient — schedule retry per e.condition (Now or WhenAppForeground)
} catch (e: IdsvrHaapiException.Unrecoverable) {
    // permanent — handle per e.action (ModifyConfiguration, InvalidPlatform, 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.