--- title: "Códigos de retorno do PKI Express" description: "Códigos de retorno das operações do PKI Express e o significado de cada um, como 00 Ok, 01 BadSyntax e 03 FileNotFound." canonical: "https://docs.lacunasoftware.com/articles/pki-express/return-codes" locale: "pt-BR" product: "PKI Express" last_updated: "2026-10-19" --- # Códigos de retorno do PKI Express As operações do PKI Express apresentam um conjunto de códigos de retorno que podem ser vistos a seguir, bem como o significado de cada código. | Códigos de retorno | Significado | |-------------------------------------|------------------------------------------------------------------------------| | 00 - Ok | Sucesso na execução da operação | | 01 - BadSyntax | Parâmetros passados não seguem o formato esperado | | 02 - UnknownError | Erro desconhecido | | 03 - FileNotFound | Arquivo não encontrado | | 04 - BadCertificate | Falha na decodificação do certificado | | 05 - BadThumbprint | Thumbprint inválido | | 06 - BadHash | To Sign Hash inválido ou algoritmo de hash não reconhecido | | 07 - BadData | To Sign Data inválido | | 08 - BadSignature | Assinatura inválida | | 09 - BadAlgorithm | Algoritmo inválido | | 10 - BadPolicy | Política inválida | | 11 - BadVisualRep | Falha no parser do arquivo de representação visual | | 12 - UndefinedFileReference | Referência indefinida a arquivo | | 13 - CertNotFound | Certificado não encontrado | | 14 - ValidationFailed | Falha na validação | | 15 - IOError | Erro na leitura de arquivos | | 16 - NoCertsWithKey | Arquivo PFX não contém certificado com chave privada | | 17 - NotActivated | PKI Express não ativado | | 18 - ActivationError | Falha na ativação do PKI Express | | 19 - BadLicense | Base-64 inválida (da licença de ativação) | | 20 - LicenseNeeded | Nenhum arquivo de licença fornecido | | 21 - InvalidLicense | Licença inválida | | 22 - AccessDenied | Falta permissão para modificar a configuração do PKI Express | | 23 - CertThumbNeeded | Nenhum thumbprint fornecido | | 24 - BadPdfChanges | Falha na execução das alterações no PDF | | 25 - UpdateNeeded | Operação necessita de versão mais recente do PKI Express | | 26 - DataFileNeeded | Nenhum Data File fornecido | | 27 - NoEncapsulatedContent | Conteúdo encapsulado faltando | | 28 - NonceNotFound | Nonce não encontrado | | 29 - DirectoryNotFound | Diretório não encontrado | | 30 - TimestampAuthorityNotAvailable | Falha na requisição do carimbo de tempo | | 31 - PolicyRequiresNetwork | Política escolhida precisa de acesso a internet (modo offline não suportado) | | 32 - TimestampOptionsRequired | Nenhum endereço URL de autoridade carimbadora fornecido | | 33 - CultureNotFound | Cultura não encontrada | | 34 - TimeZoneNotFound | Fuso horário não encontrado | | 35 - InvalidUtcOffset | Formato inválido (de Offset UTC) | | 36 - KeySizeNotSupported | Tamanho de chave não suportado | | 37 - BadKeyFormat | Formato não reconhecido (de chave) | | 38 - BadKey | Chave inválida | | 39 - InvalidTimeoutValue | Valor de timeout inválido | | 40 - CertificateMismatch | Certificado não corresponde a chave armazenada | | 41 - KeyNotFound | Chave não encontrada | | 42 - NoCertificateFile | Nenhum certificado fornecido | | 43 - BadCertificationLevel | Nível de certificação inválido | ## Códigos de retorno nas bibliotecas cliente As bibliotecas cliente executam o PKI Express a cada operação e transformam qualquer código de retorno diferente de `00 - Ok` num erro. A forma de ler o código depende da linguagem: | Linguagem | Uma operação que falha lança | Como ler o código de retorno | |---|---|---| | Java | `RuntimeException`, cuja mensagem traz a saída do PKI Express | A exceção não traz o código | | Node.js | A promise é rejeitada com `ValidationError` para `14 - ValidationFailed` ou, nos demais casos, com um erro chamado `CommandError` | `err.code`; compare-o com os `ErrorCodes` exportados, como `ErrorCodes.VALIDATION_FAILED` | | PHP | `CommandException`, com a mensagem "The command failed with code *N*: *saída*" | `$e->returnCode` | | Python | `Exception`, com a mensagem "PKI Express returned non-success code *N*: *saída*" | Apenas na mensagem | | Ruby | `PkiExpress::CommandError`, cuja mensagem traz a saída do PKI Express | `e.code` é o `Process::Status` do processo do PKI Express: leia o número com `e.code.exitstatus` | Quando a biblioteca não encontra o PKI Express, ela lança `InstallationNotFoundException` (Java, PHP) ou `InstallationNotFoundError` (Node.js, Python, Ruby); veja [configurações da biblioteca cliente](https://docs.lacunasoftware.com/articles/pki-express/config#configurações-da-biblioteca-cliente). Quando uma operação exige uma versão do PKI Express mais nova que a instalada, o código é `01 - BadSyntax`; as bibliotecas de Java, Node.js, PHP e Python terminam então a mensagem com uma dica que informa a versão necessária (no PHP, a exceção passa a ser uma `Exception` simples). Em Node.js e Ruby, `ValidationError` e `InstallationNotFoundError` são subclasses de `CommandError`; assim, em Ruby um único `rescue` trata todas elas, e nelas o `code` é um número: ```ruby begin signer.sign rescue PkiExpress::CommandError => e code = e.code.respond_to?(:exitstatus) ? e.code.exitstatus : e.code # code 14 (ValidationFailed): e.message has the validation results end ``` Em PHP, trate a `CommandException` (namespace `Lacuna\PkiExpress`) e leia o código na propriedade pública `returnCode`; trate a `InstallationNotFoundException` à parte e, por último, a `Exception` simples, da qual as duas classes de exceção herdam: ```php use Lacuna\PkiExpress\CommandException; use Lacuna\PkiExpress\InstallationNotFoundException; try { $signer->sign(); } catch (CommandException $e) { switch ($e->returnCode) { case 32: // TimestampOptionsRequired: set $signer->timestampAuthority break; case 14: // ValidationFailed: $e->getMessage() has the validation results break; default: // $e->getMessage(): "The command failed with code N: " throw $e; } } catch (InstallationNotFoundException $e) { // PKI Express was not found: see the client library settings } catch (Exception $e) { // Other errors, such as the tip asking for a newer PKI Express } ``` A `CommandException` também tem uma propriedade pública `cmd`, com a linha de comando completa que a biblioteca executou. Ela inclui os argumentos, como a senha de um arquivo PKCS #12 ou uma chave; por isso, não a grave em logs. ## Erros de validação Erros de validação ocorrem durante assinaturas, autenticações ou inspeções com validação. | Erros de Validação | Significado | |-----------------------------------------|--------------------------------------------------------------------------------| | Success | Validação bem sucedida | | CertificateNotYetValid | Na data de referência, o certificado ainda não é válido | | CertificateExpired | Na data de referência, o certificado está expirado | | CertificateRevoked | Na data de referência, o certificado estava revogado | | CertificateIssuerNotFound | Emissor do certificado não foi encontrado | | CertificateRevocationStatusUnknown | Estado de revogação do certificado não pode ser verificado. Provavelmente, o PKI Express não conseguiu acessar os certificados CRLs (veja [LAPP](https://docs.lacunasoftware.com/articles/pki-express/config/lapp)) | | CertificateChainRootNotTrusted | A raiz da cadeia de certificado não é confiável | | InvalidCertificateSignature | Assinatura não é válida, baseado na chave pública fornecida para o certificado | | DecodeError | Não foi possível decodificar parte do objeto sendo validado | | RequiredSignedAttributeMissing | Assinatura não contém todos os atributos assinados que são requeridos | | ForbiddenSignedAttributePresent | Assinatura contém um ou mais atributos assinados que são proibidos | | RequiredUnsignedAttributeMissing | Assinatura não contém todos os atributos não assinados que são requeridos | | ForbiddenUnsignedAttributePresent | Assinatura contém um ou mais atributos não assinados que são proibidos | | ContentTypeMismatch | Atributo content-type especifica um tipo de conteúdo diferente do CMS | | MessageDigestMismatch | Atributo message digest especifica um digest diferente do digest do dado assinado | | SigningCertificateDigestMismatch | Atributo signing certificate especifica um digest diferente do digest do certificado do assinante | | SignatureAlgorithmValidationFailed | Validação do algoritmo da assinatura falhou | | RevocationDataIssuedBeforeGracePeriod | Dados de revogação emitidos antes do fim do período de carência | | UncertifiedDateReference | A referência de tempo utilizada na validação da assinatura não é certificada | | SignaturePolicyMismatch | Na validação a política de assinatura difere da política fornecida | | SigningTimeOutOfCertificateValidity | Assinatura realizada fora do período de validade do certificado | | UnknownSignedAttributesPresent | Assinatura contém um ou mais atributos assinados não reconhecidos | | UnknownUnsignedAttributesPresent | Assinatura contém um ou mais atributos não assinados não reconhecidos | | TimestampWithMoreThanOneSigner | Carimbo de tempo contém mais de um assinante | | TimestampMessageImprintMismatch | Message-imprint do timestamp não é igual a computada | | CompleteReferencesMismatch | Referências completas de certificados não são válidas | | InvalidSignatureTimestamp | Carimbo de tempo da assinatura não é válido | | InvalidReferencesTimestamp | Carimbo de tempo de referenência não é válido | | InvalidSigAndRefsTimestamp | Carimbo de tempo da assinatura e de referência são inválidos | | InvalidArchiveTimestamp | Carimbo de tempo do arquivo não é válido | | InvalidKeyUsage | Certificado assinante não tem permissão para realizar esse tipo de operação | | InvalidOcspResponse | Resposta OCSP não é válida | | UnauthorizedIssuer | Emissor do certificado não é uma AC | | UnknownRootTrustStatus | Estado de confiança da raiz não conhecido | | InvalidTsl | TSL não é válido | | InvalidCrl | Certificado LCR não é válido | | CertificateIssuerValid | Emissor do certificado é confiável | | CertificateIssuerInvalid | Emissor do certificado não é confiável | | CertificateValidationFailed | Validação do certificado falhou | | SignatureVulnerableToSignerSubstitution | Assinatura é vulnerável a ataques de substituição de signatário | | InvalidXmlSignatureSchema | Validação do schema da assinatura (XSD)falhou | | XmlDSigCoreValidationFailed | Validação primária (core validation) da assinatura falhou (o digest ou assinatura estão incorretos) | | SignatureTimestampIgnored | Um carimbo de tempo de assinatura foi ignorado | | InvalidCertificationPathLen | Caminho de certificação das ACs é inválido | | SigningCertificateNotFound | Certificado do signatário não foi encontrado | | UnauthorizedACIssuer | Emissor do certificado é uma AC, portanto não pode ser usado como emissor de certificados de atributo | | AlgorithmNotAllowed | Algoritmo não é permitido | | UnacceptableSignaturePolicy | Política de assinatura não permitida | | TslNotAvailable | TSL não disponível |