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
`NOT_INITIALIZED`	SDK not initialized before use	❌
`INVALID_CONFIG`	Invalid configuration provided	❌
`AUTHENTICATION_FAILED`	API key invalid or expired	❌

Session Errors

Code	Description	Recoverable
`SESSION_CREATE_FAILED`	Failed to create verification session	✅
`SESSION_NOT_FOUND`	Session not found or already completed	❌
`SESSION_EXPIRED`	Session has expired	✅ (create new)

Channel Errors

Code	Description	Recoverable
`QR_SCAN_FAILED`	QR code scanning error	✅
`QR_INVALID_FORMAT`	Invalid mDL QR format	✅
`NFC_NOT_SUPPORTED`	Device lacks NFC hardware	❌
`NFC_NOT_ENABLED`	NFC is disabled in settings	✅
`NFC_READ_FAILED`	NFC read error	✅
`BLE_NOT_SUPPORTED`	Device lacks Bluetooth LE	❌
`BLE_NOT_ENABLED`	Bluetooth is disabled	✅
`BLE_CONNECTION_FAILED`	BLE connection error	✅

Verification Errors

Code	Description	Recoverable
`DEVICE_RESPONSE_INVALID`	Invalid response from holder's device	❌
`VERIFICATION_FAILED`	Credential verification failed	❌
`ISSUER_NOT_TRUSTED`	Credential issuer not in trust list	❌
`SIGNATURE_INVALID`	Credential signature verification failed	❌
`HOLDER_BINDING_FAILED`	Holder binding verification failed	❌

Network Errors

Code	Description	Recoverable
`NETWORK_ERROR`	Network request failed	✅
`TIMEOUT`	Operation timed out	✅
`CANCELLED`	Operation was cancelled	✅

Handling Errors

Use the fold pattern to handle success and failure cases:

MDLException Properties

The MDLException class provides detailed error information:

Common Error Scenarios

SDK Not Initialized

Device Capability Checks

Network Retry Logic

User-Friendly Error Messages

Translate error codes into user-friendly messages:

Logging and Debugging

Enable debug logging during development to troubleshoot issues:

Warning: Never enable debug logging in production builds. It may expose sensitive information in device logs.