Handle SDK errors
How the MATTR Pi mDocs Verifier SDKs report expected and unexpected errors, which errors any function can raise, and why a session error arrives on a listener rather than at the call site.
The mDocs Verifier SDKs separate errors you are expected to handle from errors that mean something has gone wrong. Knowing which is which tells you where to write a specific branch and where a generic fallback is the right answer.
Verification also produces a third thing that is not an error at all. A credential that fails its trust checks is a result, not a failure of the call. See Handling verification results.
Expected and unexpected errors
Expected errors are part of the normal operation of a function. Bluetooth is off, the holder walked away, the session timed out. These are reported with an explicit error type you can match on and handle programmatically.
Unexpected errors represent bugs, SDK misuse, or system level failures. The root cause is unknown or unrecoverable, so handle them with a generic fallback appropriate to your app, such as an error screen plus a log entry, and report them to MATTR.
How each platform reports the two kinds differs.
Both kinds are thrown, so you handle them with do and catch. Expected errors are cases of a
Swift enum such as
MobileCredentialVerifierError
or ProximityPresentationSessionError, which you catch by case. Every case conforms to
LocalizedError, so errorDescription gives you a readable message.
A function's doc comment lists the cases it can throw. Anything else that reaches your catch is
unexpected.
Session errors arrive on the listener, not at the call site
This is the part that catches people out. Creating a proximity presentation session starts an asynchronous Bluetooth exchange, so the call to create it returns before the session either establishes or fails. Errors from that phase, and from a session ending later, are delivered to the session listener you supply.
createProximityPresentationSession takes a ProximityPresentationSessionListener:
onError(error:)receives session creation failures, includingMobileCredentialVerifierError.bluetoothPermissionDenied,.bluetoothPermissionRestricted,.bluetoothDisabled,.existingProximityPresentationSession,.unsupportedCurveand.failedToCreateProximityPresentationSession. It has a default empty implementation, so it is easy to leave unimplemented by accident. Implement it.onTerminated(error:)receives the reason a session ended, as aProximityPresentationSessionTerminationError. The error isnilwhen the ending was deliberate, either because you calledterminateProximityPresentationSessionor because the holder terminated.
sendProximityPresentationRequest is different. It throws at the call site, so handle it with
do and catch.
Errors any function can raise
Some errors are not specific to a single function, so they are not listed per function.
MobileCredentialVerifierError.invalidLicenseif the SDK license failed to validate or has expired. Re-initialize the SDK to obtain a new one. See SDK Backend.MobileCredentialVerifierError.sdkNotInitializedif you call a function beforeinitialize.
Handle an expected error
do {
let response = try await MobileCredentialVerifier.shared.sendProximityPresentationRequest(
request: requests
)
// Continue with response.
} catch MobileCredentialVerifierError.invalidLicense {
// Re-initialize the SDK to obtain a new license.
} catch MobileCredentialVerifierError.illegalState {
// No session is established. Create one before sending a request.
} catch ProximityPresentationSessionError.sendRequestError {
// The request did not reach the holder. Offer a retry.
} catch {
// Unexpected. Show your generic error state and log it.
}Find the errors a function can return
The Errors topic group in the iOS Verifier SDK reference lists every public error type, and each function's page lists the cases it throws.
A credential that fails verification is a result, not an error
When the SDK verifies a response, a failed trust check does not fail the call. It comes back inside the response:
MobileCredentialVerificationFailureTypecarries the reason a credential did not verify, such as an expired credential, a missing or expired trusted issuer certificate, or a failed mDoc authentication.MobileCredentialStatusCheckFailureTypecarries the reason a revocation status check did not complete.MobileCredentialResponseErrorCodecarries the ISO/IEC 18013-5 data handling error code for a document or element the holder did not return.
A credential can verify and still be missing claims you asked for, so check the claim errors on each presentation as well as the verification result. See Handling verification results for in-person and Handling verification results for remote mobile.
Troubleshoot with SDK logs
When an error does not tell you enough, turn on native SDK logging and reproduce the failure. The log covers the internal steps the SDK took, which is usually where the real cause is. See Configure SDK logging.
Next steps
- SDK Logging: capture diagnostic output while you reproduce a failure.
- Handling verification results: the result model, which is where credential level failures live.
- SDK Backend: the licensing and registration errors above come from here.
How would you rate this page?
Last updated on