---
title: "Default fail callback"
description: "How to register a default fail callback through defaultFail in Web PKI init(), and what each Web PKI error code means."
canonical: "https://docs.lacunasoftware.com/en-us/articles/web-pki/default-error-callback"
locale: "en"
product: "Web PKI"
last_updated: "2026-10-12"
---

# Default fail callback

Although you can register specific fail callbacks on each asynchronous call, if you're always going to apply the same logic when an error occurs, it's better
to register a **default fail callback** when calling the [`init()`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#init) method:

```javascript
pki.init({
    ready: onWebPkiReady,
    defaultFail: onWebPkiFail
});

function onWebPkiFail(ex) {
    alert(ex.userMessage + ' (' + ex.code + ')');
    console.log('Web PKI error originated at ' + ex.origin + ': (' + ex.code + ') ' + ex.error);
}
```

From then on you can register the success callback only on each asynchronous call.

> **Note**
>
> When an error occurs and no fail callback is registered for that specific operation, the default fail callback is called. If no default fail callback is
> registered, an exception is thrown.

## Error codes

The `code` field of the exception passed to the fail callback tells which error occurred:

| Code | Meaning |
| --- | --- |
| `undefined` | Undefined error. |
| `internal` | Internal error. |
| `user_cancelled` | The user cancelled the operation. |
| `os_not_supported` | The user's operating system is not supported. |
| `addon_timeout` | The Internet Explorer add-on did not respond. |
| `addon_not_detected` | The Internet Explorer add-on was not detected: it is not installed or not working well. |
| `addon_send_command_failure` | The Internet Explorer add-on failed to send the command to the native component. |
| `certificate_not_found` | The selected certificate was not found in the user's store or crypto device. If a crypto device is used, check that its drivers or PKCS #11 configuration are set up properly. |
| `command_unknown` | The requested command is unknown. |
| `command_not_supported` | The requested command is not supported on the user's operating system. |
| `command_parameter_not_set` | A mandatory command parameter is missing in the request. |
| `command_invalid_parameter` | A command parameter is not valid. |
| `command_parameter_not_supported` | A command parameter is not supported on this platform. |
| `native_connect_failure` | The browser extension failed to connect to the native component. |
| `native_disconnected` | The native component disconnected from the browser extension. |
| `native_no_response` | The browser extension did not receive a response from the native component. |
| `rest_pki_get_pending_signature` | Error while getting the pending signature in `signWithRestPki()`. See [Error "Could not get pending signature"](https://docs.lacunasoftware.com/en-us/articles/rest-pki/troubleshoot/could-not-get-pending-sig). |
| `rest_pki_post_signature` | Error while sending the signature in `signWithRestPki()`. |
| `rest_pki_invalid_certificate` | Rest PKI did not accept the selected certificate. |
| `license_not_set` | A license is required and was not set. See [Licensing](https://docs.lacunasoftware.com/en-us/articles/web-pki/licensing). |
| `license_invalid` | The license passed is not valid. |
| `license_restricted` | The license passed does not allow the requested command. |
| `license_expired` | The license passed has expired. |
| `license_domain_not_allowed` | The license passed does not allow the domain being used. |
| `validation_error` | Validation error. |
| `p11_error` | Error in PKCS #11 communication. |
| `p11_token_not_found` | The selected device was not found: it is disconnected or its PKCS #11 module is not recognized. |
| `p11_not_supported` | The device does not support the requested PKCS #11 operation. |
| `keyset_not_found` | The private key of the selected certificate was not found. |
| `csp_keyset_not_defined` | Certificate key not found: check that the smart card or USB token of the selected certificate is connected to the computer, or remove it and insert it again. |
| `mobile_send_message` | With mobile integration, the library could not send the command to the mobile device. |
| `mobile_timeout` | With mobile integration, the mobile device did not respond in time. |

The library also defines these codes, not described yet: `algorithm_not_supported`, `signed_pdf_to_mark`, `json_error`,
`io_error`, `keychain_error`, `keychain_sign_error`, `decode_error`, `csp_invalid_algorithm`, `csp_invalid_provider_type`,
`mobile_not_authorized`, `command_decrypt_error`, `blocked_domain` and `invalid_operation`.

## See also

* [`userMessage` parameter documentation](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.exceptionmodel.html#usermessage) (available since [API version 1.4](https://docs.lacunasoftware.com/en-us/articles/web-pki/api-reference/versions#v1-4))
* [FailCallback documentation](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.failcallback.html) (available since [API version 1.3](https://docs.lacunasoftware.com/en-us/articles/web-pki/api-reference/versions#v1-3))
* [Promise class documentation](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.promise.html)
* [ErrorCodes documentation](https://docs.lacunasoftware.com/content/typedocs/web-pki/enums/_lacuna_web_pki_d_.lacunawebpki.errorcodes.html)