JavaScript SDK
Error Handling
Understand verification outcomes, error codes, and which callbacks fire for each non-success result.
Error Handling
The SDK provides structured non-success outcomes through VerificationOutcome.
type VerificationOutcome = {
code: VerificationErrorCode
message: string
raw?: unknown
}Use code for your UI logic and analytics. Treat raw as debugging-only data.
Outcome codes
| Code | Callback | Meaning |
|---|---|---|
UNDER_AGE | onDenied | User does not meet the age requirement |
USER_CANCELLED | onCancelled | User cancelled before completing the flow |
POPUP_CLOSED | onCancelled | User manually closed the popup |
POPUP_TIMEOUT | onCancelled | Popup stayed open too long without a result |
POPUP_BLOCKED | onError | Browser blocked the popup |
NETWORK_ERROR | onError | Verification startup failed because of a network or API problem |
TOKEN_INVALID | onError | Missing, expired, or invalid token |
UNTRUSTED_ORIGIN | onError | Result came from an origin that the SDK does not trust |
UNKNOWN_ERROR | onError | Unexpected failure |
Important nuance: UNDER_AGE
UNDER_AGE is the one denied outcome and should be handled through onDenied.
The backend response behind this outcome can represent both a genuine under-age result and a user opting out inside MitID, so your UI should stay neutral and simply tell the user that the age requirement was not met.
Example pattern
init({
publicKey: 'pk_test_your_key',
ageToVerify: 18,
redirectUri: 'https://your-app.com/verification-result',
onVerified: () => {
hideError()
},
onDenied: (outcome) => {
showMessage('You do not meet the age requirement.')
report('denied', outcome.code)
},
onCancelled: (outcome) => {
showMessage('Verification was cancelled before completion.')
report('cancelled', outcome.code)
},
onError: (outcome) => {
showMessage('Verification failed. Please try again.')
report('error', outcome.code)
},
})About onFailure
onFailure still exists for backwards compatibility.
- It is a legacy catch-all callback
- It is still triggered alongside the more specific granular callbacks
- New integrations should primarily use
onDenied,onCancelled, andonError
Recommended UX
UNDER_AGE: show a clear business messageUSER_CANCELLED,POPUP_CLOSED,POPUP_TIMEOUT: let the user retryPOPUP_BLOCKED: tell the user to allow popups or fall back to redirect flowNETWORK_ERROR,TOKEN_INVALID,UNKNOWN_ERROR: show a retry path and log the failure