> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/tratamento-de-erros.md). # Tratamento de Erros ### Códigos de Status HTTP A API utiliza os códigos de status padrão do protocolo HTTP para indicar o sucesso ou a falha básica de uma requisição. Falhas nesta camada geralmente indicam problemas de comunicação, formatação ou autenticação, antes mesmo da requisição chegar ao HSM. `200` · ***Success*** A requisição foi recebida, compreendida e processada com sucesso. {% hint style="info" %} Nota: Um status **HTTP 200** não garante que a operação no HSM foi um sucesso, apenas que a comunicação ocorreu sem falhas. Sempre verifique o `retCode` no corpo da resposta. {% endhint %} `400` · ***Bad Request*** A requisição está malformada, faltando parâmetros obrigatórios ou com sintaxe JSON inválida. `401` · ***Unauthorized*** O seu `access_token` é inválido, expirou ou não foi enviado no cabeçalho `Authorization`. `402` · ***Over Quota*** A cota do seu plano para este endpoint foi excedida. `404` · ***Not Found*** O endpoint ou recurso solicitado não existe. Verifique a URL da requisição. `422` · ***Validation Error*** A requisição está bem formatada, mas contém erros de validação semântica (ex: um `keyName` que não existe). `429` · ***Too Many Requests*** Você atingiu o limite de requisições por segundo (Rate Limit). Aguarde alguns instantes antes de tentar novamente. `50X` · ***Internal Server Error*** Ocorreu um erro interno nos servidores do HoP API. Caso o erro persista, entre em contato com o suporte. ### Códigos de Resposta do HSM (retCode) Mesmo que a sua requisição retorne um HTTP `200 Success`, a operação criptográfica dentro do HSM pode falhar (por exemplo, se você tentar validar um PIN incorreto ou usar uma chave incompatível). O resultado real da operação do HSM sempre estará no campo `retCode` do corpo da resposta (JSON). Abaixo está a lista de códigos padrão e seus significados: #### ✅ Sucesso `00` · ***No error*** A operação criptográfica foi executada com sucesso absoluto. Não há erros. *** #### 🔑 Erros de Validação e Chaves (01 a 29) `01` · ***Verification failure or warning of imported key parity error*** Falha na verificação de criptogramas (ex: MAC ou Assinatura incorreta) ou aviso de que a chave importada possui erro de paridade. `02` · ***Key inappropriate length for algorithm*** O tamanho da chave fornecida não é adequado para o algoritmo criptográfico solicitado (ex: tentar usar uma chave DES simples em uma operação TDES). `04` · ***Invalid key type code*** O código do tipo de chave (`keyType` / `keyName`) enviado é inválido ou não é suportado por este endpoint. `05` · ***Invalid key length flag*** A flag que define o tamanho da chave (Key Scheme, como U, T, X) é inválida. `10` · ***Source key parity error*** Erro de paridade detectado na chave de origem (Source Key). A chave pode estar corrompida. `11` · ***Destination key parity error or key all zeros*** Erro de paridade na chave de destino, ou a chave fornecida é composta apenas por zeros (chave nula). `12` **· *****Contents of user storage not available. Reset, power-down or overwrite*** O conteúdo do armazenamento seguro não está disponível no momento. `13` · ***Invalid LMK Identifier*** O identificador da Local Master Key (LMK) enviado ou configurado é inválido. `14` · ***PIN encrypted under LMK pair 02-03 is invalid*** O bloco de PIN fornecido é inválido. Este é o erro mais comum quando um usuário digita a senha incorreta ou quando o PIN Block foi malformado na origem. `15` · ***Invalid input data (invalid format, invalid characters, or not enough data provided)*** Os dados de entrada enviados na requisição são inválidos. Pode ser um formato incorreto, caracteres não permitidos ou falta de dados obrigatórios. `16` · ***Console or printer not ready or not connected*** O HSM não consegue se comunicar com o console ou impressora interna (erro de infraestrutura). `17` · ***Unrecognized message header*** O cabeçalho da mensagem enviada ao HSM não foi reconhecido. `20` · ***PIN block does not contain valid values*** O formato do PIN Block fornecido contém valores que não respeitam o padrão matemático exigido (ex: ISO 0, ISO 1). `21` · ***Invalid index value*** O valor de índice (Index Value) fornecido para derivação de chaves é inválido. `22` · ***Invalid account number*** O Número da Conta (PAN / Número do Cartão) fornecido é inválido ou não condiz com o bloco de PIN. `23` · ***Invalid PIN block format code*** O código que define o formato do PIN Block (ex: 01 para ISO-1) não é suportado ou é inválido. `24` · ***PIN is fewer than 4 or more than 12 digits in length*** A senha (PIN) extraída possui um tamanho não permitido pela norma. Deve ter entre 4 e 12 dígitos. `25` · ***Decimalization table error*** A tabela de decimalização fornecida (usada em validações de PIN legadas, como IBM3624) contém erros. `26` · ***Invalid key scheme*** O esquema de chaves (Key Scheme) é inválido para a operação solicitada. `27` · ***Incompatible key length*** O tamanho da chave é incompatível com a chave de transporte (ex: tentar criptografar uma chave TDES sob uma chave ZMK que é apenas DES simples). `28` · ***Invalid key type*** O tipo de chave fornecido é inválido. `29` · ***Key function not permitted*** A função solicitada não é permitida para esta chave específica. `30` · ***Invalid reference number*** O número de referência da transação é inválido. `31` · ***Insufficient solicitation entries for batch*** Entradas de solicitação insuficientes para o processamento em lote. `32` · ***AES not licensed*** O HSM não possui licença para executar operações com o algoritmo AES. `33` · ***LMK key change storage is corrupted*** O armazenamento de alteração de chaves LMK está corrompido. `39` · ***Fraud detection*** Detecção de fraude. O HSM bloqueou a transação por anomalias. *** #### ⚙️ Erros de Hardware, Criptografia e Sistema (40 a 90) `40` · ***Invalid checksum*** O checksum (KCV) fornecido ou calculado é inválido. `41` · ***Internal hardware/software error: bad RAM, invalid error codes, etc.*** Erro crítico interno de hardware ou software no HSM. `42` · ***DES failure*** Falha interna na execução do algoritmo DES. `43` · ***RSA Key Generation Failure*** Falha ao gerar as chaves assimétricas RSA. `46` · ***Invalid tag for encrypted PIN*** A tag fornecida para o PIN criptografado é inválida. `47` · ***Algorithm not licensed*** O algoritmo criptográfico não possui licença ativada no equipamento. `48` · ***Key cannot be encrypted by a 3DES LMK*** A chave não pode ser criptografada por uma LMK do tipo 3DES. `49` · ***Private key error, report to supervisor*** Erro na chave privada; contate o administrador do HSM. `51` · ***Invalid message header*** O cabeçalho da mensagem interna é inválido. `65` · ***Transaction Key Scheme set to None*** O esquema de chaves da transação foi definido como nulo (None). `67` · ***Command not licensed*** O HSM não possui licença para executar este comando. `68` · ***Command has been disabled*** O comando solicitado foi desativado nas configurações do HSM. `69` · ***PIN block format has been disabled*** O formato de PIN Block solicitado foi desativado (comum em padrões inseguros). `74` · ***Invalid digest info syntax (no hash mode only)*** Sintaxe de informações de digest inválida. `75` · ***Single length key masquerading as double or triple length key*** Uma chave de tamanho simples está tentando se passar por uma chave dupla ou tripla. `76` · ***RSA public key length error or RSA encrypted data length error*** Erro no tamanho da chave pública RSA ou no tamanho dos dados criptografados. `77` · ***Clear data block error*** Erro no bloco de dados em texto claro. `78` · ***Private key length error*** Erro no tamanho da chave privada. `79` · ***Hash algorithm object identifier error*** Erro no identificador do objeto do algoritmo de hash. `80` · ***Data length error*** A quantidade de dados do MAC (ou outros dados) é maior ou menor do que o esperado. `81` · ***Invalid certificate header 82 Invalid check value length*** Cabeçalho de certificado inválido ou tamanho do valor de checagem inválido. `83` · ***Key block format error*** Erro geral de formato no Key Block. `84` · ***Key block check value error*** Erro no valor de checagem (Check Value) do Key Block. `85` · ***Invalid OAEP Mask Generation Function*** Função de geração de máscara OAEP inválida. `86` · ***Invalid OAEP MGF Hash Function*** Função de hash OAEP MGF inválida. `87` · ***OAEP Parameter Error*** Erro de parâmetro no encapsulamento OAEP. `90` · ***Data parity error in the request message received by the HSM*** Erro de paridade de dados na mensagem de requisição recebida pelo equipamento. *** #### 📦 Erros de Blocos de Chaves (Key Blocks / TR-31) (A1 a D3) `A1` · ***Incompatible LMK schemes*** Os esquemas da LMK são incompatíveis. `A2` · ***Incompatible LMK identifiers*** Os identificadores da LMK são incompatíveis. `A3` · ***Incompatible key block LMK identifiers*** Os identificadores da LMK do Key Block são incompatíveis. `A4` · ***Key block authentication failure*** Falha na autenticação da assinatura/MAC do Key Block. `A5` · ***Incompatible key length*** O tamanho da chave encapsulada é incompatível. `A6` · ***Invalid key usage*** O uso pretendido para a chave encapsulada é inválido. `A7` · ***Invalid algorithm*** O algoritmo definido no Key Block é inválido. `A8` · ***Invalid mode of use*** O modo de uso (Mode of Use) da chave é inválido. `A9` · ***Invalid key version number*** O número de versão da chave é inválido. `AA` · ***Invalid export field*** O campo de controle de exportação é inválido. `AB` · ***Invalid number of optional blocks*** A quantidade de blocos opcionais informada no cabeçalho é inválida. `AC` · ***Optional header block error*** Erro no bloco de cabeçalho opcional. `AD` · ***Key status optional block error*** Erro no bloco opcional de status da chave. `AE` · ***Invalid start date/time*** A data e hora de início definidas no Key Block são inválidas. `AF` · ***Invalid end date/time*** A data e hora de término definidas no Key Block são inválidas. `B0` · ***Invalid encryption mode*** O modo de criptografia (Encryption Mode) é inválido. `B1` · ***Invalid authentication mode*** O modo de autenticação do bloco é inválido. `B2` · ***Miscellaneous key block error*** Erro diversificado ou não classificado na estrutura do Key Block. `B3` · ***Invalid number of optional blocks*** A contagem de blocos opcionais está incorreta. `B4` · ***Optional block data error*** Os dados contidos em um bloco opcional estão inválidos. `B5` · ***Incompatible components*** Os componentes da chave fornecidos são incompatíveis. `B6` · ***Incompatible key status optional blocks*** Os blocos de status de chave opcionais são incompatíveis. `B7` · ***Invalid change field*** O campo de alteração do bloco está inválido. `B8` · ***Invalid old value*** O valor antigo (Old Value) fornecido está incorreto. `B9` · ***Invalid new value*** O novo valor (New Value) fornecido está incorreto. `BA` · ***No key status block in the key block*** Não foi encontrado o bloco de status da chave dentro do Key Block. `BB` · ***Invalid wrapping key*** A chave de transporte (Wrapping Key) utilizada é inválida. `BC` · ***Repeated optional block*** Existe um bloco opcional repetido dentro do pacote. `BD` · ***Incompatible key types*** Tipos de chaves incompatíveis detectados. `BE` · ***Invalid key block header ID*** A identificação (ID) do cabeçalho do Key Block é inválida. `D3` · ***The wrapping key has a lower security strength than the key being wrapped*** **Violação PCI**: A chave de transporte possui uma força de segurança menor que a chave que está sendo protegida. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ftcoders.first-tech.com/landing-page/tratamento-de-erros.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.