> 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/modulo-key-manager/troubleshooting-erros-e-apendices.md).

# Troubleshooting, Erros e Apêndices

### Troubleshooting, Erros e Apêndices

Esta secção serve como o guia de referência operacional e de diagnóstico para a integração com o módulo Key Manager.

#### Catálogo de Códigos de Erro (`retCode`)

O catálogo de erros é partilhado entre todos os endpoints do módulo. A coluna "Origem" indica se o erro foi detetado pela camada de validação da API ou diretamente pelo HSM Thales.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Código</th><th>Significado</th><th>Origem</th><th>Ação Recomendada</th></tr></thead><tbody><tr><td><code>-1</code></td><td>Erro interno</td><td>API</td><td>Erro genérico. O <code>retDescription</code> traz tipicamente <code>"Internal error: &#x3C;mensagem>"</code>. Abrir chamado com a First Tech.</td></tr><tr><td><code>01</code></td><td>Erro de paridade na chave (Aviso)</td><td>HSM</td><td>A chave gerada/importada tem um byte de paridade incorreto. Tipicamente é um <em>warning</em> (aviso).</td></tr><tr><td><code>04</code></td><td>Tipo de chave inválido</td><td>HSM</td><td>O valor enviado em <code>keyName</code> não é reconhecido. Verifique a lista de tipos suportados.</td></tr><tr><td><code>05</code></td><td>Flag de comprimento inválido</td><td>API</td><td>O <code>keySizeType</code> está fora dos valores aceites (S/D/T/A/B/C).</td></tr><tr><td><code>07</code></td><td>Tipo de ZKA Master Key inválido</td><td>HSM</td><td>O tipo da ZMK referenciada não corresponde ao esperado. Verifique <code>zmk_TMK_keyId</code> ou <code>ZMK_keyId</code>.</td></tr><tr><td><code>10</code></td><td>Erro de paridade na ZMK/TMK</td><td>HSM</td><td>A chave-mestra referenciada está corrompida no banco. Recadastrar via <code>ImportZMK</code>.</td></tr><tr><td><code>11</code></td><td>Erro de paridade na chave</td><td>HSM</td><td>A chave referenciada está corrompida. Em <code>ImportZMK</code>, indica KCV divergente (validar com a contraparte).</td></tr><tr><td><code>44</code></td><td>Migração não permitida</td><td>HSM</td><td>A operação (<code>TranslateLMK</code>) viola regras de Compliance PCI HSM V3. Contatar o suporte.</td></tr><tr><td><code>45</code></td><td>Tipo de chave de destino inválido</td><td>HSM</td><td>Em <code>TranslateLMK</code>: a chave de destino tem tipo incompatível.</td></tr><tr><td><code>68</code></td><td>Comando desabilitado</td><td>HSM</td><td>Operação desabilitada no HSM. Contatar o suporte.</td></tr><tr><td><code>137</code></td><td>Malformação da requisição</td><td>API</td><td>JSON malformado, tipo de dado errado ou combinação inválida (ex.: <code>is_ephemeral = true</code> sem <code>key_TTL_minutes</code>) .</td></tr><tr><td><code>155</code></td><td>Chave não encontrada</td><td>API</td><td>O <code>keyId</code> não existe ou pertence a outro <code>client_id</code> .</td></tr></tbody></table>

***

### Guia de Troubleshooting

Sintomas comuns e resoluções para integrações iniciais :

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Sintoma Observado</th><th>Causa Provável</th><th>Como Resolver</th></tr></thead><tbody><tr><td>HTTP 400 com <code>retCode = 137</code></td><td>JSON malformado ou combinação inválida.</td><td>Validar o <em>body</em> contra o <em>schema</em>; conferir tipos numéricos vs <em>strings</em>.</td></tr><tr><td>HTTP 404 com <code>retCode = 155</code> em Export/Import</td><td>O <code>ZMK_keyId</code> ou o <code>keyId</code> não existem.</td><td>Listar as chaves no banco para confirmar os aliases exatos.</td></tr><tr><td>HTTP 400 com <code>retCode = 11</code> no <code>ImportZMK</code></td><td>O KCV informado não bate com o KCV calculado pelo HSM após decifrar o Key Block.</td><td>Confirmar com a contraparte o KCV correto; verificar erro de transcrição.</td></tr><tr><td>HTTP 400 com <code>retCode = 07</code> no <code>GenerateKey</code> (<code>modeFlag=1</code>)</td><td>O <code>zmk_TMK_keyId</code> aponta para uma chave que não é do tipo ZMK ou TMK.</td><td>Confirmar que o alias passado corresponde realmente a uma ZMK/TMK no banco.</td></tr><tr><td>Em <code>ExportKey</code> (scheme=X917), <code>retCode = 04</code></td><td>Tentativa de exportar chave AES com esquema X9.17.</td><td>Trocar o <code>export_scheme</code> para <code>TR31</code> ou <code>TKBF</code> (X9.17 só suporta DES).</td></tr><tr><td>Chave deixou de funcionar após horas</td><td>A chave foi gerada com <code>is_ephemeral = true</code> e expirou.</td><td>Se precisa de chave permanente, gere com <code>is_ephemeral = false</code>.</td></tr><tr><td>KCV difere do informado pela contraparte</td><td>Diferença na convenção de cálculo de KCV (ex.: Thales usa os primeiros 3 bytes de zeros encriptados).</td><td>Confirmar o algoritmo de KCV utilizado pela contraparte.</td></tr></tbody></table>

***

### Apêndice A - `TranslateLMK` e a Migração Hop V3 → V4

O endpoint `TranslateLMK` re-criptografa chaves entre ambientes (V3 para V4) . Abaixo estão os comportamentos técnicos esperados após uma tradução bem-sucedida:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Aspecto</th><th>Comportamento Esperado</th></tr></thead><tbody><tr><td><code>keyId</code></td><td>Mantém o mesmo alias. O que muda é apenas o LMK interno que protege a chave.</td></tr><tr><td><code>KCV</code></td><td>Mantém o mesmo valor. O KCV é calculado sobre o material da chave em si, e não sobre a proteção LMK.</td></tr><tr><td>Consumo em Módulos</td><td>Continuam 100% funcionais imediatamente após a tradução (CVV, EMV, PIN, etc.).</td></tr><tr><td>Reversibilidade</td><td>A operação é tipicamente irreversível. Voltar ao LMK antigo exigiria nova chamada inversa, reforçando a importância da validação pós-migração.</td></tr></tbody></table>

***

### Apêndice B - Matrizes de Combinações Válidas

#### B.1 `keyName` x `keySizeType`

A matriz abaixo indica os tamanhos e algoritmos suportados por cada tipo de chave .

<table data-header-hidden="false" data-header-sticky><thead><tr><th>keyName</th><th>S (DES)</th><th>D (3DES)</th><th>T (3DES T)</th><th>A (AES-128)</th><th>B (AES-192)</th><th>C (AES-256)</th></tr></thead><tbody><tr><td>ZMK / TMK</td><td>-</td><td>Sim</td><td>Sim</td><td>Sim</td><td>-</td><td>Sim</td></tr><tr><td>ZPK / ZAK</td><td>-</td><td>Sim</td><td>-</td><td>Sim</td><td>-</td><td>Sim</td></tr><tr><td>ZEK / DEK</td><td>Sim</td><td>Sim</td><td>Sim</td><td>Sim</td><td>-</td><td>Sim</td></tr><tr><td>BDK</td><td>-</td><td>Sim</td><td>Sim</td><td>Sim</td><td>-</td><td>Sim</td></tr><tr><td>CVK / KERG</td><td>-</td><td>Sim</td><td>-</td><td>Sim</td><td>-</td><td>-</td></tr></tbody></table>

#### B.2 `export_scheme` x `keySizeType`

Compatibilidade entre os formatos de exportação e os algoritmos :

<table data-header-hidden="false" data-header-sticky><thead><tr><th>export_scheme</th><th>DES / 3DES (S, D, T)</th><th>AES (A, B, C)</th></tr></thead><tbody><tr><td>X917</td><td>Sim</td><td><p>Não (Esquema exclusivamente DES)</p><p><a class="button secondary"></a></p></td></tr><tr><td>TR31</td><td>Sim</td><td>Sim</td></tr><tr><td>TKBF</td><td>Sim</td><td>Sim</td></tr></tbody></table>

***

### Apêndice C - Glossário

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Sigla</th><th>Significado</th><th>Contexto</th></tr></thead><tbody><tr><td>AES / DES</td><td>Advanced / Data Encryption Standard</td><td>Algoritmos de criptografia simétrica.</td></tr><tr><td>BDK / UDK</td><td>Base Derivation Key / Unique Derived Key</td><td>Chaves do esquema DUKPT para terminais POS.</td></tr><tr><td>HSM</td><td>Hardware Security Module</td><td>Dispositivo de alta segurança (Thales) que executa a criptografia.</td></tr><tr><td>KCV</td><td>Key Check Value</td><td>Hash curto (6 caracteres hex) que atua como impressão digital da chave.</td></tr><tr><td>Key Block</td><td>-</td><td>Estrutura proprietária (ou TR-31) que embrulha a chave com um MAC sob LMK.</td></tr><tr><td>LMK</td><td>Local Master Key</td><td>A chave-mestra interna do HSM.</td></tr><tr><td>ZMK / ZPK</td><td>Zone Master / PIN Key</td><td>Chaves-mestras e de trabalho para comunicação segura entre instituições.</td></tr></tbody></table>


---

# 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/modulo-key-manager/troubleshooting-erros-e-apendices.md?ask=<question>&goal=<endgoal>
```

`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.