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 .

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

---

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 :

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