---
title: "Callback de erro padrão"
description: "Como registrar um callback de erro padrão (defaultFail) no init() do Web PKI, e o que significa cada código de erro do Web PKI."
canonical: "https://docs.lacunasoftware.com/articles/web-pki/default-error-callback"
locale: "pt-BR"
product: "Web PKI"
last_updated: "2026-10-12"
---

# Callback de erro padrão

Embora seja possível registrar callbacks de erro específicos em cada chamada assíncrona, se você vai sempre empregar a mesma lógica quando um erro ocorrer,
é mais prático registrar um **callback de erro padrão** ao chamar o método [`init()`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#init):

```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);
}
```

A partir de então, você pode registrar apenas o callback de sucesso em cada chamada assíncrona.

> **Observação**
>
> Quando um erro ocorre e não há callback de erro registrado para a operação, o callback de erro padrão é chamado. Se também não houver callback de erro padrão registrado,
> uma exceção é lançada.

## Códigos de erro

O campo `code` da exceção recebida pelo callback de erro indica qual erro ocorreu:

| Código | Significado |
| --- | --- |
| `undefined` | Erro indefinido. |
| `internal` | Erro interno. |
| `user_cancelled` | O usuário cancelou a operação. |
| `os_not_supported` | O sistema operacional do usuário não é suportado. |
| `addon_timeout` | O add-on do Internet Explorer não respondeu. |
| `addon_not_detected` | O add-on do Internet Explorer não foi detectado: não está instalado ou não está funcionando bem. |
| `addon_send_command_failure` | O add-on do Internet Explorer não conseguiu enviar o comando ao componente nativo. |
| `certificate_not_found` | O certificado selecionado não foi encontrado no repositório do usuário nem no dispositivo criptográfico. Se for usado um dispositivo criptográfico, verifique se os drivers ou a configuração PKCS #11 estão corretos. |
| `command_unknown` | O comando requisitado é desconhecido. |
| `command_not_supported` | O comando requisitado não é suportado no sistema operacional do usuário. |
| `command_parameter_not_set` | Falta na requisição um parâmetro obrigatório do comando. |
| `command_invalid_parameter` | Um parâmetro do comando não é válido. |
| `command_parameter_not_supported` | Um parâmetro do comando não é suportado nesta plataforma. |
| `native_connect_failure` | A extensão do navegador não conseguiu se conectar ao componente nativo. |
| `native_disconnected` | O componente nativo se desconectou da extensão do navegador. |
| `native_no_response` | A extensão do navegador não recebeu resposta do componente nativo. |
| `rest_pki_get_pending_signature` | Erro ao obter a assinatura pendente no método `signWithRestPki()`. Veja [Erro "Could not get pending signature"](https://docs.lacunasoftware.com/articles/rest-pki/troubleshoot/could-not-get-pending-sig). |
| `rest_pki_post_signature` | Erro ao enviar a assinatura no método `signWithRestPki()`. |
| `rest_pki_invalid_certificate` | O Rest PKI não aceitou o certificado selecionado. |
| `license_not_set` | Uma licença é necessária e não foi configurada. Veja [Licenciamento](https://docs.lacunasoftware.com/articles/web-pki/licensing). |
| `license_invalid` | A licença informada não é válida. |
| `license_restricted` | A licença informada não permite o comando requisitado. |
| `license_expired` | A licença informada expirou. |
| `license_domain_not_allowed` | A licença informada não permite o domínio em uso. |
| `validation_error` | Erro de validação. |
| `p11_error` | Erro na comunicação PKCS #11. |
| `p11_token_not_found` | O dispositivo selecionado não foi encontrado: está desconectado ou o módulo PKCS #11 não foi reconhecido. |
| `p11_not_supported` | O dispositivo não suporta a operação PKCS #11 requisitada. |
| `keyset_not_found` | A chave privada do certificado selecionado não foi encontrada. |
| `csp_keyset_not_defined` | Chave do certificado não encontrada: verifique se o smart card ou token USB do certificado selecionado está conectado ao computador, ou remova-o e insira-o novamente. |
| `mobile_send_message` | Na integração com dispositivo móvel, a biblioteca não conseguiu enviar o comando ao dispositivo. |
| `mobile_timeout` | Na integração com dispositivo móvel, o dispositivo não respondeu a tempo. |

A biblioteca também define estes códigos, ainda sem descrição: `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` e `invalid_operation`.

## Veja também

* [Documentação do parâmetro `userMessage`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.exceptionmodel.html#usermessage) (disponível desde a [versão 1.4 da API](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions#v1-4))
* [Documentação do *callback* de erro FailCallback](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.failcallback.html) (disponível desde a [versão 1.3 da API](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions#v1-3))
* [Documentação da classe Promise](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.promise.html)
* [Documentação do enum ErrorCodes](https://docs.lacunasoftware.com/content/typedocs/web-pki/enums/_lacuna_web_pki_d_.lacunawebpki.errorcodes.html)