Error Handling#

Failures during a HAAPI flow fall into three categories: retryable errors (a transient condition the client should attempt again), unrecoverable errors (a configuration or environment problem that needs human intervention), and OAuth protocol errors (the server understood the request and explicitly rejected it). Each category is surfaced differently and demands a different response.

Retryable Errors#

Retryable failures happen when the network is briefly unavailable, when the server asks for a fresh DPoP nonce, or when the device’s resources are temporarily out of reach. The SDKs expose them as a distinct type — IdsvrHaapiException.Retryable on Android, HaapiError with a retryable recovery suggestion on iOS — carrying a RetryCondition that tells the client when retry is appropriate:

• Now — retry immediately with an exponential backoff.
• WhenAppForeground — defer the retry until the app is in the foreground, then attempt again.

Specific retryable subtypes include socket interruptions, DNS or connectivity blips, HTTP 5xx responses with a Retry-After header, and the use_dpop_nonce case where the client must refresh its nonce and resubmit.

Unrecoverable Errors#

Unrecoverable failures cannot be resolved by retrying. They signal that the client is misconfigured, the device is on an unsupported platform, or the server has explicitly denied the request. The SDKs expose an UnrecoverableAction hint that maps to a remediation path:

• ModifyConfiguration — surface the cause to the developer and adjust client settings.
• InvalidPlatform — the device cannot satisfy the protocol’s prerequisites.
• IntrospectCause — inspect the wrapped cause for follow-up.

Typical triggers include access denied by server policy, missing attestation or token-binding capabilities, parsing failures on unexpected payloads, and unsupported content types.

OAuth Protocol Errors#

When the token endpoint returns a well-formed OAuth error (invalid_grant, invalid_dpop_proof, and similar), the SDK returns it as a parsed ErrorTokenResponse rather than throwing. On invalid_grant the SDK additionally clears any stored DPoP key pair so the next flow starts cleanly — the appropriate UX response is to prompt the user to re-authenticate.