> 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-pin/tratamento-de-erros-e-operacao.md).

# Tratamento de Erros e Operação

### Códigos de Erro (Taxonomia Completa)

Nas respostas de erro (HTTP 400, 404, 500), o campo `retCode` indica a categoria da falha ocorrida no processamento da API ou na validação criptográfica do HSM .

<table data-header-hidden="false" data-header-sticky><thead><tr><th>retCode</th><th>HTTP Típico</th><th>Significado</th><th>Ação Sugerida</th></tr></thead><tbody><tr><td><code>-1</code></td><td>400/500</td><td>Erro interno genérico</td><td>Falha do serviço criptográfico. Aplicar <em>retry</em> com <em>backoff</em>. Se persistir, escalar para o suporte técnico.</td></tr><tr><td><code>01</code></td><td>400</td><td>Falha na verificação do PIN</td><td>Indica inconsistência de formato/chave ou, dependendo da integração, falha de validação.</td></tr><tr><td><code>10</code></td><td>400/500</td><td>Erro de paridade (Chave Origem)</td><td>Problema criptográfico grave na chave. A chave está corrompida. Requer intervenção do suporte técnico.</td></tr><tr><td><code>11</code></td><td>400/500</td><td>Erro de paridade (Chave Destino)</td><td>Análogo ao código 10, aplicado à chave de destino.</td></tr><tr><td><code>17</code></td><td>400</td><td>Tradução de PIN desabilitada</td><td>O comando <code>TranslatePin</code> não está habilitado no contrato ou perfil associado ao seu <code>client_id</code>.</td></tr><tr><td><code>68</code></td><td>400</td><td>Comando desabilitado</td><td>O comando PIN em questão está desabilitado comercialmente para o cliente.</td></tr><tr><td><code>69</code></td><td>400</td><td>Formato do PinBlock desabilitado</td><td>O <code>pibBlockFmt</code> informado é válido no HSM, mas encontra-se desabilitado para o seu <em>tenant</em>.</td></tr><tr><td><code>88</code></td><td>400</td><td>PinBlock contém PIN de tamanho zero</td><td>O bloco foi decifrado, mas o PIN extraído tem 0 dígitos. Sinaliza problema na geração do bloco na origem (terminal) ou PAN inconsistente.</td></tr><tr><td><code>137</code></td><td>400</td><td>Malformação da requisição</td><td><em>Payload</em> JSON inválido, campo obrigatório ausente ou nome de campo incorreto (ex: <code>pinBlockFmt</code> em vez de <code>pibBlockFmt</code>).</td></tr><tr><td><code>155</code></td><td>404</td><td>Chave não encontrada</td><td>O alias informado em <code>keyId</code>, <code>keyIdSrc</code> ou <code>keyIdDst</code> não existe ou não pertence ao seu cliente.</td></tr></tbody></table>

***

### Boas Práticas e Armadilhas Comuns

#### Boas Práticas

* Mascaramento de Logs (Obrigatório): Auditorias de PCI PIN reprovam integrações que registam dados sensíveis. O PAN completo e os campos `hPibBlock` e `hPinHost` NUNCA devem constar nos *logs* da sua aplicação (ex: mascare o PAN como `111122******4444` e suprima os PinBlocks) .
* Diferenciar Falha Técnica de Recusa: Um `HTTP 200` com `retValid: false` (PIN incorreto) é uma decisão de negócio e não um erro técnico. Instrumente métricas separadas; misturá-las com falhas 400/500 dificultará o rastreio de incidentes reais .
* Token JWT Unificado: O mesmo token Bearer atende a todos os módulos (EMV, PIN, Key Manager, Crypto, CVV, PAN, RSA). Mantenha um *cache* partilhado na sua arquitetura .
* Validação de KCV: Ao provisionar chaves com o suporte, valide o KCV (*Key Check Value*) no ambiente de homologação. KCVs incorretos são a principal causa dos erros `10` e `11` em produção .

#### Armadilhas Comuns na Integração

1. Grafia do campo `pibBlockFmt`: Como mencionado, a API exige a grafia com "pib". Tentar utilizar "pinBlockFmt" gerará imediatamente o erro `137` .
2. Incompatibilidade Algoritmo/Formato: Formatos como o `05` (ISO 4) exigem obrigatoriamente chaves AES. Tentativas de decifrar o formato `05` com chaves 3DES causarão o erro `69` ou falhas de paridade .
3. PAN Inconsistente: Se o PAN enviado no *request* divergir do PAN efetivamente utilizado pelo terminal para gerar o PinBlock, a operação de extração do PIN falhará, resultando frequentemente no erro `88` (PIN de tamanho zero).
4. Ausência de KSN no DUKPT: Quando o `keyIdSrc` for um BDK, a ausência dos campos `ksn` ou `ksn_desc` invalidará a requisição, pois o HSM não terá como derivar a chave de sessão.

***

### Troubleshooting

Guia de triagem rápida para anomalias observadas durante a fase de integração e produção :

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Sintoma</th><th>Causa Provável</th><th>Ação Sugerida</th></tr></thead><tbody><tr><td>HTTP 200 / <code>retValid: false</code> sempre</td><td>Chave errada ou PAN inconsistente.</td><td>Validar rigorosamente se o PAN do <em>request</em> corresponde ao PAN utilizado no cálculo no terminal.</td></tr><tr><td>HTTP 400 (<code>retCode 137</code>)</td><td>Erro estrutural no <em>payload</em>.</td><td>Inspecionar a sintaxe JSON e garantir o uso correto de <code>pibBlockFmt</code>.</td></tr><tr><td>HTTP 400 (<code>retCode 88</code>)</td><td>PIN decifrado com tamanho zero.</td><td>Verificar integridade do PAN e, em cenários DUKPT, confirmar se o KSN não sofreu mutação.</td></tr><tr><td>HTTP 404 (<code>retCode 155</code>)</td><td>Chave não localizada.</td><td>O erro não distingue entre Origem e Destino; verifique ambos os <em>aliases</em> no Key Manager.</td></tr><tr><td>HTTP 400/500 (<code>retCode 10</code> ou <code>11</code>)</td><td>Paridade de chave corrompida.</td><td>Escalar para o suporte técnico para reprovisionamento do <em>alias</em>.</td></tr><tr><td>HTTP 401 intermitente</td><td>Token expirado.</td><td>Implementar <em>cache</em> com renovação proativa (<em>pre-fetch</em>).</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-pin/tratamento-de-erros-e-operacao.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.