# Solução de problemas
Este guia ajuda você a diagnosticar falhas durante uma integração com o SDK White Label e a decidir o que fazer em cada caso. Ele cobre as falhas que você trata no seu próprio aplicativo. Entre elas estão problemas de warm-up, pagamentos recusados, erros de serviço, falhas na leitura do cartão, timeouts e estornos que não se concluem.
Para o catálogo completo de códigos de resultado e mensagens, consulte a [Referência de códigos de erro](/pt/getnet-toolbox/sdk-white-label/reference-sdk/error-codes).
## Leia primeiro o código de resultado
Toda falha traz um código de resultado com um prefixo que indica a classe da falha. Leia o prefixo antes de qualquer outra coisa.
| Prefixo | Classe | De onde vem |
| :--- | :--- | :--- |
| `00` | Aprovado | A transação foi concluída com sucesso. |
| `1-` | Erro do terminal | Terminal local, leitura do cartão ou operador (por exemplo, `1-02` cancelado, `1-21` erro genérico do terminal). |
| `33-` | Erro de host | Serviço de pagamento (SEP): um erro HTTP ou uma recusa do emissor. |
O código chega ao seu aplicativo em `TransactionResult.result`, acompanhado de um `resultMessage` legível. Trate `00` como aprovação e qualquer outro valor como não aprovação.
Os erros de host estão migrando do prefixo antigo `4-xx` para `33-xx` — os dígitos permanecem os mesmos (`4-503` passa a ser `33-503`). Terminais que ainda não foram atualizados podem retornar `4-xxx`. Trate `4-xxx` e `33-xxx` como equivalentes.
## Identifique a tela de erro
Nos fluxos com cartão, o SDK exibe uma de duas telas de erro antes de devolver o controle ao seu aplicativo. O Pix tem a própria tela de erro.
| Tela | Quando aparece | O que o operador deve fazer |
| :--- | :--- | :--- |
|  | O terminal leu o cartão corretamente, mas o emissor recusou o pagamento (`33-`). | A recusa vem do banco do portador do cartão, não do terminal. Peça outro cartão ou oriente o cliente a falar com o banco dele. |
|  | O serviço de pagamento falhou ou estava indisponível — um erro de host ou um timeout (`33-5xx`). | Verifique o status da transação antes de tentar de novo, para não cobrar duas vezes. Se continuar acontecendo em vários terminais, trate como incidente de plataforma. |
## Classifique a falha
Toda não aprovação cai em uma destas categorias. A categoria indica se você trata a falha no seu aplicativo, pede uma ação ao operador ou aciona a Getnet.
| Categoria | O que significa | O que você faz |
| :--- | :--- | :--- |
| Portador / cartão | O emissor ou o cartão recusou a operação. | Peça outro cartão ou oriente o cliente a falar com o banco. Não é falha do terminal nem do aplicativo. |
| Transitória — nova tentativa | Uma condição temporária. | Aguarde alguns segundos e tente de novo. Depois de um timeout, consulte a transação primeiro. |
| Duplicada / em andamento | A transação pode já estar concluída ou cancelada. | Verifique o recibo impresso ou consulte o pagamento antes de tentar de novo. Não repita a operação às cegas. |
| Referência não encontrada | O `paymentId` ou a referência não corresponde a nenhuma transação. | Confirme o `paymentId` e o ambiente usado no estorno ou na consulta. |
| Configuração do estabelecimento / produto | O estabelecimento, o produto, a bandeira ou o terminal não está habilitado para esta operação. | Reúna o código do terminal e o ID do estabelecimento e acione a Getnet. |
| Autenticação | O terminal não conseguiu se autenticar no gateway. | Confirme o ambiente e verifique se você configurou credenciais válidas. |
| Integração / requisição | A validação rejeitou a requisição, ou a requisição estava malformada. | É um problema de software — capture o payload de resultado e corrija a integração. |
| Plataforma / sistema | Uma falha no lado do servidor. | Tente de novo uma vez, após uma breve espera. Se persistir ou afetar vários terminais, trate como incidente de plataforma. |
## Cenários comuns
Cada cenário apresenta o sintoma, a causa provável e a solução.
### O warm-up falha e o SDK nunca fica pronto
O SDK informa `Failure(cause)` por meio de `setOnWarmUpStatus`, ou uma operação nunca começa.
**Causa.** O warm-up carrega a configuração do terminal e se autentica no serviço de pagamento. Ele falha quando não há conexão de rede, quando as credenciais estão erradas ou quando o terminal não está registrado.
**Solução**
1. Verifique o Wi-Fi ou os dados móveis do terminal.
2. Analise o código de erro do warm-up. De `-1` a `-5` são condições de rede — tente de novo. `401` indica que o `clientId` / `clientSecret` ou o ambiente está errado. `404` indica que o terminal não está registrado para esta configuração.
3. Para recuperar, chame `ApoloSdk.shutdown()` e depois configure e execute `build()` novamente.
4. Se um `401`, `404` ou `422` persistir, confirme as credenciais, o `terminalCode` e o ambiente com a Getnet.
Consulte os códigos de warm-up na [Referência de códigos de erro](/pt/getnet-toolbox/sdk-white-label/reference-sdk/error-codes).
### Um pagamento é recusado
O terminal lê o cartão normalmente, mas o resultado é `33-` e a tela "Pagamento recusado" aparece.
**Causa.** O emissor recusou a autorização — por exemplo, saldo insuficiente, cartão bloqueado ou cartão vencido. É uma decisão do lado do portador do cartão, não uma falha do terminal.
**Solução**
1. Peça outro cartão ao cliente ou oriente-o a falar com o banco.
2. Escale o caso somente se um cartão que o cliente diz ser válido falhar em vários terminais.
### "Pagamento interrompido" — erro de serviço
A tela "Pagamento interrompido" aparece com um código `33-5xx` (por exemplo, `33-500`, `33-503`, `33-504`).
**Causa.** O serviço de pagamento falhou ou ficou temporariamente indisponível — uma condição de servidor ou de timeout.
**Solução**
1. Não tente de novo imediatamente.
2. Consulte a transação pelo `paymentId` para confirmar se ela foi concluída.
3. Se não foi, tente de novo uma vez, após uma breve espera.
4. Se persistir ou afetar vários terminais, trate como incidente de plataforma e acione a Getnet.
### O cartão não é lido
O terminal repete "insira, aproxime ou passe o cartão", ou a leitura por aproximação falha.
**Causa.** A leitura por aproximação ou por chip falhou. Em geral, esse é um fallback normal, não um erro.
**Solução**
1. Peça ao cliente para inserir o chip. Se o chip falhar, peça para passar a tarja magnética.
2. Se o terminal detectar vários cartões ao mesmo tempo, peça ao cliente para apresentar um único cartão, longe de outros cartões ou da carteira.
3. Se um cartão específico falhar em todos os métodos, peça outro cartão.
### Timeout — você não sabe se o cliente foi cobrado
O resultado é um timeout (`33-504`) ou a operação termina sem um desfecho claro.
**Causa.** A resposta não chegou dentro da janela de tempo limite, então o desfecho é desconhecido — a cobrança pode ter sido concluída ou não.
**Solução**
1. Não inicie uma nova venda com o mesmo valor por enquanto.
2. Consulte a transação pelo `paymentId` para confirmar se ela foi autorizada.
3. Inicie uma nova venda somente depois de confirmar que a primeira não foi concluída.
### Um estorno ou cancelamento falha com "not found"
O estorno retorna um `33-404` com a mensagem "not found".
**Causa.** O `paymentId` ou o ambiente usado no estorno não corresponde à transação original. Uma referência errada é a causa mais comum.
**Solução**
1. Confirme o `paymentId` da transação original.
2. Confirme que você está no mesmo ambiente em que fez a venda.
3. Tente o estorno de novo com a referência corrigida.
### A transação é informada como duplicada ou já existente
O resultado indica que a transação já está em andamento, já foi concluída ou já foi cancelada.
**Causa.** A operação já terminou, ou ainda está em processamento.
**Solução**
1. Verifique o recibo impresso ou consulte o pagamento antes de agir.
2. Não repita a operação até confirmar o estado real dela.
## Antes de acionar a Getnet
Algumas falhas exigem o suporte da Getnet: configuração, autenticação, um `5xx` persistente, um terminal travado ou um erro interno de EMV. Reúna estas informações antes de entrar em contato, para que o suporte localize a transação e reproduza o problema.
| Reúna | Detalhe |
| :--- | :--- |
| Código de resultado | O `TransactionResult.result` completo (por exemplo, `33-503`, `1-21`) e a mensagem exibida na tela. |
| `error_code` / `reason_code` | Nos erros de host, o `error_code` e o `reason_code` do payload da resposta (`details[]`). |
| `paymentId` | O `paymentId` (e o `orderId`, se houver) da transação afetada. |
| Terminal | O número de série do terminal e o `terminalCode` configurado. |
| Ambiente | Pré-produção, homologação ou produção — qual build o dispositivo executa. |
| Data e hora | A data, a hora e o fuso horário do evento. |
| Abrangência | Um cartão ou terminal em comparação com vários — caso isolado ou generalizado. |
| Passos para reproduzir | Valor, meio de pagamento, bandeira do cartão e o que o operador fez. |
## Próximos passos
* [Referência de códigos de erro](/pt/getnet-toolbox/sdk-white-label/reference-sdk/error-codes) — o catálogo completo de códigos de host, de cartão e de warm-up.
* [Referência do resultado da transação](/pt/getnet-toolbox/sdk-white-label/reference-sdk/transaction-result) — os campos de resultado e os payloads retornados ao seu aplicativo.
* [Referência de inicialização](/pt/getnet-toolbox/sdk-white-label/reference-sdk/initialization) — os estados do warm-up e como se recuperar de um `Failure`.
* [Registre telemetria](/pt/getnet-toolbox/sdk-white-label/how-to-guides-sdk/record-telemetry) — registre suas próprias entradas de diagnóstico para correlacionar com os traces do SDK.