cybercore-signer/docs/errors.md

Catálogo Estruturado de Erros

Especificação Unificada de Códigos de Erro (CcspErrorCode), Status HTTP e Tratamento no SDK

O CyberCore Signer adota uma taxonomia estrita e estável de erros estruturados, garantindo que o agente desktop Java, a API REST do protocolo CCSP/1 e o SDK JavaScript manipulem falhas com previsibilidade e sem expor detalhes internos sensíveis ao usuário final.

---

1. Tabela Completa de Códigos de Erro

Código de Erro (CcspErrorCode)	Status HTTP	Descrição do Erro	Ação Recomendada para a Aplicação Web
CERTIFICATE_NOT_FOUND	404 Not Found	O certificado indicado pelo certificate_hint não foi localizado na máquina.	Solicitar ao usuário selecionar novamente o certificado via getCertificates().
CERTIFICATE_EXPIRED	422 Unprocessable	O certificado digital selecionado ultrapassou sua data limite de validade.	Orientar o usuário a renovar o certificado digital junto à autoridade certificadora (AC).
CERTIFICATE_INVALID	400 Bad Request	Estrutura ASN.1/X.509 corrompida ou ainda não iniciada (NotBefore).	Verificar integridade do arquivo .pfx ou relógio do sistema operacional.
PRIVATE_KEY_NOT_AVAILABLE	404 Not Found	O certificado está presente mas a chave privada não está acessível no repositório.	Em tokens A3, verificar se o middleware/driver do token está instalado corretamente.
TOKEN_NOT_FOUND	404 Not Found	Nenhum dispositivo criptográfico físico ou leitora de cartão foi detectado.	Solicitar ao usuário conectar o token USB ou inserir o smartcard no leitor.
TOKEN_REMOVED	503 Service Unavail	O token USB ou cartão foi desconectado fisicamente durante o processamento.	Orientar o usuário a reconectar o token e reiniciar a operação de assinatura.
PIN_REQUIRED	400 Bad Request	O token exige PIN para liberar a chave privada e nenhum PIN foi informado.	Exibir campo para inserção do PIN do dispositivo.
PIN_INCORRECT	400 Bad Request	O PIN digitado para o token A3 é incorreto.	Alertar o usuário sobre o risco de bloqueio do cartão (PUK) após tentativas consecutivas.
PKCS11_ERROR	500 Server Error	Falha na biblioteca DLL/SO do middleware ou driver do fabricante.	Verificar a instalação do SafeSign, SafeNet, GD Burti ou OpenSC.
SIGNATURE_FAILED	400 Bad Request	Falha criptográfica na geração dos bytes da assinatura digital.	Reiniciar a operação ou verificar integridade do algoritmo especificado.
APPLICATION_NOT_AUTHORIZED	401 Unauthorized	A aplicação web teve autorização recusada pelo usuário ou não foi cadastrada.	Notificar o usuário que é necessário aceitar a solicitação na janela do CyberCore.
REQUEST_EXPIRED	422 Unprocessable	A validade temporal (expires_at) da requisição foi ultrapassada.	Gerar nova requisição de assinatura com timestamp atualizado no backend/frontend.
REPLAY_DETECTED	409 Conflict	O nonce informado já foi processado anteriormente dentro da janela ativa.	Sempre gerar um UUID criptograficamente novo para cada chamada de assinatura.
INVALID_ORIGIN	403 Forbidden	O cabeçalho Origin não confere com o domínio autorizado da aplicação.	Conectar a partir da URL e domínio homologados pelo usuário.
UNSUPPORTED_ALGORITHM	400 Bad Request	O algoritmo de hash ou assinatura solicitado não é suportado pelo provedor.	Utilizar os algoritmos padrão homologados (SHA256withRSA).
USER_CANCELLED	400 Bad Request	O usuário clicou em Cancelar ou fechou o diálogo nativo de confirmação.	Tratar como cancelamento voluntário do usuário sem exibir alerta de erro crítico.
PROVIDER_NOT_AVAILABLE	500 Server Error	O provedor criptográfico necessário não está ativo no sistema operacional.	Verificar o Windows Certificate Store ou bibliotecas de runtime do Java.
COMMUNICATION_ERROR	503 Service Unavail	Erro de socket, timeout na confirmação visual ou porta ocupada.	Verificar se o CyberCore Signer está em execução e se a porta 21325 está livre.

---

2. Estrutura do Payload JSON de Erro

Em qualquer resposta com status diferente de 200 OK, o payload retornado pela API CCSP/1 adota o seguinte formato:

{
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "error",
  "error_code": "PIN_INCORRECT",
  "message": "O PIN informado para o token A3 é incorreto."
}

---

3. Tratamento Tipado no SDK JavaScript

No SDK @cybercore/signer-sdk, cada código estruturado possui uma classe de erro correspondente herdando de CyberCoreError:

import {
  UserCancelledError,
  PinIncorrectError,
  TokenNotFoundError,
  CertificateNotFoundError
} from '@cybercore/signer-sdk/errors';

try {
  const result = await signer.sign({
    certificateId: cert.id,
    digest: documentoDigest
  });
} catch (error) {
  if (error instanceof UserCancelledError) {
    console.info('Assinatura cancelada voluntariamente pelo usuário.');
  } else if (error instanceof PinIncorrectError) {
    alert('PIN incorreto! Verifique a senha do seu token para evitar o bloqueio.');
  } else if (error instanceof TokenNotFoundError) {
    alert('Dispositivo não detectado. Por favor, conecte seu token USB na porta do computador.');
  } else if (error instanceof CertificateNotFoundError) {
    alert('O certificado selecionado não foi encontrado ou expirou.');
  } else {
    console.error('Erro na operação de assinatura:', error.message);
  }
}