> 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-rsa/schemas-e-codigos-de-erro.md).

# Schemas e Códigos de Erro

Esta secção detalha os modelos de objeto (*schemas*) utilizados para o envio de requisições e processamento de respostas, bem como a taxonomia completa dos erros técnicos que podem ser retornados pelo HSM ou pela camada de validação da API.

### Modelos de Dados (Schemas)

#### Schemas de Entrada

Estes são os objetos JSON esperados no corpo (*body*) das requisições para cada *endpoint*.

`ImportPublicKeyInput` (Utilizado no *endpoint* `Import`):

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>integer</code></td><td>Sim</td><td>Identificador numérico do cliente. Mínimo: 1.</td></tr><tr><td><code>publicKeyEncoding</code></td><td><code>integer</code></td><td>Sim</td><td>Regra de codificação da chave pública (1, 2 ou 3).</td></tr><tr><td><code>publicKey</code></td><td><code>string</code></td><td>Sim</td><td>Chave pública DER ASN.1 em hexadecimal.</td></tr></tbody></table>

`ExportKeyInput` (Utilizado no *endpoint* `Export`):

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>integer</code></td><td>Sim</td><td>Identificador numérico do cliente.</td></tr><tr><td><code>keyId</code></td><td><code>string</code></td><td>Sim</td><td>Alias da chave simétrica DES/AES/HMAC a ser exportada.</td></tr><tr><td><code>padModeId</code></td><td><code>integer</code></td><td>Sim</td><td>Modo de <em>padding</em> (<code>1</code> = PKCS#1 v1.5, <code>2</code> = OAEP).</td></tr><tr><td><code>mgfHashFunction</code></td><td><code>integer</code></td><td>Não</td><td>Função hash MGF. Obrigatório apenas se <code>padModeId = 2</code>.</td></tr><tr><td><code>publicKey</code></td><td><code>string</code></td><td>Sim</td><td>Chave pública em formato Key Block Thales (resultado do <code>Import</code>).</td></tr><tr><td><code>keyBlockType</code></td><td><code>integer</code></td><td>Sim</td><td>Tipo do Key Data Block (apenas <code>3</code> suportado).</td></tr></tbody></table>

#### Schemas de Saída

`ReturnSingle` (Resposta de Sucesso): Utilizado tanto no `Import` quanto no `Export`. O módulo RSA retorna sempre um único valor criptográfico por chamada .

| **Campo**        | **Tipo**  | **Obrigatório** | **Descrição**                                        |
| ---------------- | --------- | --------------- | ---------------------------------------------------- |
| `retCode`        | `integer` | Não             | `0` para sucesso. Outros valores indicam erro.       |
| `retValid`       | `boolean` | Não             | Indica sucesso da operação.                          |
| `retValue`       | `string`  | Não             | Chave importada ou exportada em formato hexadecimal. |
| `retDescription` | `string`  | Não             | Descrição textual do resultado.                      |

`ReturnError` (Respostas HTTP 400, 404 e 500): Possui o mesmo formato do `ReturnSingle`, mas com a flag `retValid` definida como `false` e o `retCode` preenchido com o código específico da falha do HSM ou da API. A mensagem de detalhe é enviada no campo `retDescription` .

***

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

O módulo PayShield RSA possui um catálogo de erros extenso, refletindo o rigor das validações criptográficas e de formatação exigidas pelos padrões PCI HSM V3 . A coluna "Origem" ajuda a identificar se a recusa partiu da validação da API ou do próprio *Hardware Security Module* (HSM) .

<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>01</code></td><td>Falha na verificação do MAC</td><td>HSM</td><td>Key Block Thales corrompido ou alterado após o <code>Import</code>. Refazer o <code>Import</code> e tentar novamente com o novo valor.</td></tr><tr><td><code>02</code></td><td>Falha na verificação do <em>check value</em></td><td>HSM</td><td>A chave simétrica referenciada por <code>keyId</code> está corrompida na base de dados. Recadastrar a chave.</td></tr><tr><td><code>03</code></td><td>Tipo de codificação de chave pública inválido</td><td>HSM</td><td>Verificar se o <code>publicKeyEncoding</code> corresponde ao tipo real da chave enviada.</td></tr><tr><td><code>04</code> / <code>50</code></td><td>Estrutura DER ASN.1 mal formada</td><td>HSM</td><td>A estrutura de dados está incorreta. Reverificar o processo de geração da chave pública na origem.</td></tr><tr><td><code>05</code></td><td>Tipo de chave DES/AES inválido</td><td>HSM</td><td>A chave <code>keyId</code> não é do tipo suportado. Apenas chaves DES, AES ou HMAC são exportáveis.</td></tr><tr><td><code>06</code></td><td>Identificador de criptografia inválido</td><td>HSM</td><td>Combinação inválida de parâmetros criptográficos. Revisar o <code>padModeId</code>.</td></tr><tr><td><code>07</code></td><td>Identificador de modo de <em>padding</em> inválido</td><td>API</td><td>O <code>padModeId</code> está fora dos valores aceites (deve ser <code>1</code> ou <code>2</code>).</td></tr><tr><td><code>08</code></td><td>Erro no Key Block HMAC</td><td>HSM</td><td>Falha ao tentar exportar chave HMAC devido a bloco interno inválido. Recadastrar a chave.</td></tr><tr><td><code>10</code></td><td>Erro de paridade na chave DES</td><td>HSM</td><td>A chave simétrica DES referenciada está corrompida. Recadastrar a chave.</td></tr><tr><td><code>34</code></td><td>Valor de identificador hash HMAC inválido</td><td>HSM</td><td>O identificador hash da chave HMAC não é reconhecido. Recadastrar a chave.</td></tr><tr><td><code>47</code></td><td>Algoritmo não licenciado</td><td>HSM</td><td>O HSM não possui a licença ativa para o algoritmo solicitado. Acionar suporte.</td></tr><tr><td><code>68</code></td><td>Comando desabilitado</td><td>HSM</td><td>A operação está bloqueada na configuração do HSM. Acionar suporte.</td></tr><tr><td><code>76</code></td><td>Erro no comprimento do Key Data Block</td><td>HSM</td><td>O tamanho do bloco da chave pública (<code>publicKey</code>) está incorreto.</td></tr><tr><td><code>81</code></td><td>Tipo de Key Data Block inválido</td><td>API</td><td>O <code>keyBlockType</code> está fora dos valores aceites (apenas <code>3</code> é suportado).</td></tr><tr><td><code>83</code></td><td>Erro no formato do Key Block</td><td>HSM</td><td>O <code>publicKey</code> enviado no <code>Export</code> NÃO está no formato Key Block Thales. Use o <code>retValue</code> retornado pelo <code>Import</code>.</td></tr><tr><td><code>84</code></td><td>Erro no <em>check value</em> do Key Block</td><td>HSM</td><td>O Key Block foi adulterado em trânsito. Refazer o <code>Import</code>.</td></tr><tr><td><code>85</code></td><td>Função MGF OAEP inválida</td><td>API</td><td>O <code>mgfHashFunction</code> foi enviado incorretamente num contexto PKCS#1 v1.5, ou o valor está fora do <em>range</em> aceite.</td></tr><tr><td><code>86</code></td><td>Função hash MGF OAEP inválida</td><td>API</td><td>O valor do <code>mgfHashFunction</code> não consta na lista aceita (<code>1</code>, <code>5</code>, <code>6</code>, <code>7</code>, <code>8</code>).</td></tr><tr><td><code>87</code> / <code>88</code></td><td>Erro no parâmetro OAEP</td><td>HSM</td><td>Parâmetros OAEP incompatíveis ou erro genérico. Validar acordo prévio de <em>padding</em>.</td></tr><tr><td><code>D3</code></td><td>Critérios PCI HSM V3 não atendidos</td><td>HSM</td><td>A chave não atende às regras de segurança PCI HSM V3 (ex: tamanho, uso ou algoritmo).</td></tr><tr><td><code>D4</code></td><td>Chave pública ECC inválida</td><td>HSM</td><td>A chave ECC não está no formato X9.62 <em>uncompressed</em> válido (aplicável quando <code>publicKeyEncoding = 3</code>).</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-rsa/schemas-e-codigos-de-erro.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.