Handle SDK errors
How the MATTR Pi mDocs Holder SDKs report expected and unexpected errors, which errors any function can raise, and how to handle each kind.
The mDocs Holder 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.
Expected and unexpected errors
Expected errors are part of the normal operation of a function. The holder declined authentication, no trusted issuer certificate matched, the transaction code was wrong. 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
MobileCredentialHolderError,
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.
Errors any function can raise
Some unexpected errors are not specific to a single function, so they are not listed per function.
MobileCredentialHolderError.invalidLicenseif you have configured an SDK Backend and the license failed to validate or has expired. Re-initialize the SDK to obtain a new one.MobileCredentialHolderError.sdkNotInitializedif you call a function beforeinitialize.
Handle an expected error
do {
let results = try await MobileCredentialHolder.shared.retrieveCredentials(
authorizationSession: session,
authorizationCode: authorizationCode
)
// Continue with results.
} catch MobileCredentialHolderError.invalidLicense {
// Re-initialize the SDK to obtain a new license.
} catch MobileCredentialHolderError.connectivityError(let message) {
// The device could not reach the issuer. Offer a retry.
print(message)
} catch {
// Unexpected. Show your generic error state and log it.
}Find the errors a function can return
The Errors topic group in the iOS Holder SDK reference lists every public error type, and each function's page lists the cases it throws.
Credential verification failures are not SDK errors
When the SDK verifies a credential, a failed check is reported as a result rather than as an error.
VerificationResult carries a
MobileCredentialVerificationFailureType
with the reason, such as an expired credential, a missing trusted issuer certificate, or a revoked
status. Read it from the result, not from a catch block or an isErr() branch. See
Revocation status check.
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.
- Activity Logs: a holder-facing record of what the SDK did, which is a different thing from SDK logs.
- SDK Backend: the licensing and registration errors above only apply when this is configured.
How would you rate this page?
Last updated on