Error Handling - Grantiva

All SDK operations throw GrantivaError, which conforms to LocalizedError.

Error types

Error	When	Suggested action
`deviceNotSupported`	Physical device doesn’t support App Attest (old hardware or restricted region)	Degrade gracefully; this is a permanent device limitation
`simulatorAPIKeyRequired`	`validateAttestation()` called in the iOS Simulator without an API key configured	Initialize with `Grantiva(teamId:apiKey:)` — see Simulator Setup
`attestationNotAvailable`	App Attest not supported in this region	Degrade gracefully
`networkError(Error)`	Network communication failed	Retry with backoff
`validationFailed`	Server rejected the attestation	Device may be compromised — block or challenge
`tokenExpired`	JWT token has expired	Call `refreshToken()` or `validateAttestation()`
`configurationError`	Invalid Bundle ID or Team ID	Check SDK initialization
`keyGenerationFailed`	Can’t create attestation key	Retry; may indicate Keychain issue
`challengeExpired`	Server challenge timed out	Retry — the SDK handles this automatically
`invalidResponse`	Unexpected server response format	Check SDK/server version compatibility
`rateLimited`	Too many requests	Back off and retry after delay
`feedbackNotAvailable`	Feedback not enabled for this tenant	Check your plan includes feedback
`reattestRequired`	Server reports attestation key has drifted (rpIdHash or signature mismatch)	The SDK self-heals: it clears the cached keyId and re-runs attestation automatically. Avoid wrapping SDK calls in retry loops that re-call `validateAttestation()` — the SDK already retries once internally
`serverError(reason: String)`	Server-side validation failure with a developer-readable reason	Bind the associated value (`case .serverError(let reason)`) and log it; do not show the raw reason to end users
`keyAlreadyAttested`	Apple’s DCAppAttestService rejected `attestKey` because the keyId was already attested in a prior session	The SDK self-heals by clearing the stored keyId and generating a fresh one. If the retry also fails, this error surfaces to the caller — typically after a re-install or Keychain wipe
`assertionKeyInvalid` (2.0.5+)	Apple rejected `generateAssertion()` because the stored keyId references a key that can no longer produce assertions (backup restore, device transfer, drifted local state)	The SDK self-heals: it clears the stored keyId and tokens and runs one full re-attestation. Surfaces only if that also fails
`limitExceeded(limit: Int, current: Int)` (2.1.0+)	Your organization’s Monthly Active Device limit was reached and the grace period has expired (HTTP 402 from the server)	Existing devices keep working; only new devices hit this. Upgrade your plan, or degrade gracefully on-device

Example

do {
    let result = try await grantiva.validateAttestation()
} catch let error as GrantivaError {
    switch error {
    case .simulatorAPIKeyRequired:
        // Initialize with Grantiva(teamId:apiKey:) for Simulator builds
        print("Configure an API key for Simulator builds — see Simulator Setup")
    case .deviceNotSupported:
        // Physical device doesn't support App Attest (old hardware / restricted region)
        print("App Attest not available on this device")
    case .networkError(let underlying):
        print("Network error: \(underlying.localizedDescription)")
    case .validationFailed:
        print("Device verification failed")
    case .tokenExpired:
        let refreshed = try await grantiva.refreshToken()
    case .serverError(let reason):
        // Log reason for diagnostics
        print("Server error: \(reason)")
    case .rateLimited:
        try await Task.sleep(for: .seconds(5))
    default:
        print(error.localizedDescription)
    }
}

Localized descriptions

GrantivaError conforms to LocalizedError and provides both an errorDescription (what went wrong) and a failureReason (what to do about it):

GrantivaError.simulatorAPIKeyRequired.errorDescription
// "App Attest is unavailable in the iOS Simulator — pass an API key to
//  Grantiva(teamId:apiKey:) for simulator builds"

GrantivaError.deviceNotSupported.errorDescription
// "This device does not support App Attest functionality"

GrantivaError.rateLimited.errorDescription
// "Too many requests. Please try again later"

GrantivaError.serverError(reason: "invalid_key").errorDescription
// "Attestation failed: invalid_key"

GrantivaError.limitExceeded(limit: 1000, current: 1042).errorDescription
// "Monthly attestation limit reached (1042/1000 MAD). Upgrade at grantiva.io/upgrade."

GrantivaError.rateLimited.failureReason
// "You have exceeded the rate limit for this action"

Both properties are non-optional in practice — every case returns a string.