Error Handling

Handle errors gracefully and provide a good user experience when issues occur.

Error Codes

The SDK uses typed error codes to help you identify and handle specific error conditions. Some errors are recoverable (can be retried), while others require user action or indicate permanent failures.

Initialization Errors

Code	Description	Recoverable
`.notInitialized`	SDK not initialized before use	❌
`.invalidConfiguration`	Invalid configuration provided	❌
`.authenticationFailed`	API key invalid or expired	❌

Session Errors

Code	Description	Recoverable
`.sessionCreateFailed`	Failed to create verification session	✅
`.sessionNotFound`	Session not found or already completed	❌
`.sessionExpired`	Session has expired	✅ (create new)

Channel Errors

Code	Description	Recoverable
`.qrScanFailed`	QR code scanning error	✅
`.qrInvalidFormat`	Invalid mDL QR format	✅
`.nfcNotSupported`	Device lacks NFC hardware	❌
`.nfcNotEnabled`	NFC is disabled in settings	✅
`.nfcReadFailed`	NFC read error	✅
`.bleNotSupported`	Device lacks Bluetooth LE	❌
`.bleNotEnabled`	Bluetooth is disabled	✅
`.bleConnectionFailed`	BLE connection error	✅

Verification Errors

Code	Description	Recoverable
`.deviceResponseInvalid`	Invalid response from holder's device	❌
`.verificationFailed`	Credential verification failed	❌
`.issuerNotTrusted`	Credential issuer not in trust list	❌
`.signatureInvalid`	Credential signature verification failed	❌
`.holderBindingFailed`	Holder binding verification failed	❌

Network Errors

Code	Description	Recoverable
`.networkError`	Network request failed	✅
`.timeout`	Operation timed out	✅
`.cancelled`	Operation was cancelled	✅

MDLError Structure

The MDLError struct provides detailed error information:

Handling Errors

Use Swift's do-catch pattern to handle errors:

Common Error Constants

The SDK provides pre-defined error instances for convenience:

SwiftUI Error Handling

Integrate error handling with SwiftUI's alert system:

UIKit Error Handling

Logging Errors

Enable debug logging for troubleshooting during development:

Warning: Disable debug logging in production builds to avoid exposing sensitive information in logs.

Best Practices

Always handle errors – Don't ignore errors. Every async operation should have error handling.
Provide user-friendly messages – Translate error codes into messages users can understand and act on.
Offer recovery options – For recoverable errors, provide clear paths to retry or resolve the issue.
Log for debugging – Log errors during development but be careful about logging in production.
Check device capabilities early – Before starting NFC/BLE verification, check if the device supports it.

Session Management – Handle session lifecycle and state
Verification Channels – QR, NFC, and BLE channel details