# Solución de problemas
Esta guía te ayuda a diagnosticar fallas durante una integración con el SDK White Label y a decidir qué hacer con cada una. Cubre las fallas que manejas en tu propia aplicación. Incluye problemas de warm-up, pagos rechazados, errores de servicio, fallas de lectura de tarjeta, tiempos de espera agotados y reembolsos fallidos.
Para el catálogo completo de códigos de resultado y mensajes, consulta [Referencia de códigos de error](/es/getnet-toolbox/sdk-white-label/reference-sdk/error-codes).
## Lee primero el código de resultado
Cada falla trae un código de resultado con un prefijo que indica la clase de falla. Lee el prefijo antes que nada.
| Prefijo | Clase | De dónde viene |
| :--- | :--- | :--- |
| `00` | Aprobada | La transacción tuvo éxito. |
| `1-` | Error de terminal | Terminal local, lectura de tarjeta u operador (por ejemplo, `1-02` cancelada, `1-21` error genérico de terminal). |
| `33-` | Error de host | Servicio de pagos (SEP): un error HTTP o un rechazo del emisor. |
El código llega a tu aplicación en `TransactionResult.result`, con un `resultMessage` legible. Trata `00` como aprobación y cualquier otro valor como no aprobación.
Los errores de host están migrando del prefijo antiguo `4-xx` a `33-xx`: los dígitos se mantienen (`4-503` pasa a ser `33-503`). Los terminales que aún no se actualizaron pueden seguir devolviendo `4-xxx`. Trata `4-xxx` y `33-xxx` como equivalentes.
## Identifica la pantalla de error
En los flujos con tarjeta, el SDK muestra una de dos pantallas de error antes de devolver el control a tu aplicación. Pix tiene su propia pantalla de error.
| Pantalla | Cuándo aparece | Qué debe hacer el operador |
| :--- | :--- | :--- |
|  | El terminal leyó la tarjeta correctamente, pero el emisor rechazó el pago (`33-`). | El rechazo viene del banco del titular, no del terminal. Pide otra tarjeta o indica al cliente que contacte a su banco. |
|  | El servicio de pagos falló o no estaba disponible: un error de host o un tiempo de espera agotado (`33-5xx`). | Consulta el estado de la transacción antes de reintentar, para no cobrar dos veces. Si sigue ocurriendo en varios terminales, trátalo como un incidente de plataforma. |
## Clasifica la falla
Cada no aprobación entra en una de estas categorías. La categoría te indica si la manejas en tu aplicación, si pides una acción al operador o si contactas a Getnet.
| Categoría | Qué significa | Qué haces |
| :--- | :--- | :--- |
| Titular / tarjeta | El emisor o la tarjeta rechazó la operación. | Pide otra tarjeta o indica al cliente que contacte a su banco. No es una falla del terminal ni de la aplicación. |
| Transitoria — reintenta | Una condición temporal. | Espera unos segundos y reintenta. Después de un tiempo de espera agotado, consulta primero la transacción. |
| Duplicada / en curso | La transacción puede estar ya completa o cancelada. | Revisa el recibo impreso o consulta el pago antes de reintentar. No reintentes a ciegas. |
| Referencia no encontrada | El `paymentId` o la referencia no coincide con ninguna transacción. | Confirma el `paymentId` y el entorno usado en el reembolso o la consulta. |
| Configuración de comercio / producto | El comercio, el producto, la marca de tarjeta o el terminal no está habilitado para esta operación. | Reúne el código del terminal y el ID del comercio, y contacta a Getnet. |
| Autenticación | El terminal no pudo autenticarse con el gateway. | Confirma el entorno y que configuraste credenciales válidas. |
| Integración / solicitud | La validación rechazó la solicitud, o la solicitud estaba mal formada. | Es un problema de software: captura el payload del resultado y corrige la integración. |
| Plataforma / sistema | Una falla del lado del servidor. | Reintenta una vez después de una breve espera. Si persiste o afecta a varios terminales, trátalo como un incidente de plataforma. |
## Escenarios comunes
Cada escenario indica el síntoma, su causa probable y la solución.
### El warm-up falla y el SDK nunca queda listo
El SDK informa `Failure(cause)` a través de `setOnWarmUpStatus`, o una operación nunca inicia.
**Causa.** El warm-up carga la configuración del terminal y se autentica con el servicio de pagos. Falla si no hay conexión de red, si las credenciales son incorrectas o si el terminal no está registrado.
**Solución**
1. Revisa el Wi-Fi o los datos móviles del terminal.
2. Inspecciona el código de error del warm-up. De `-1` a `-5` son condiciones de red: reintenta. `401` significa que el `clientId` / `clientSecret` o el entorno son incorrectos. `404` significa que el terminal no está registrado para esta configuración.
3. Para recuperarte, llama a `ApoloSdk.shutdown()` y luego configura y ejecuta `build()` de nuevo.
4. Si un `401`, `404` o `422` persiste, confirma las credenciales, el `terminalCode` y el entorno con Getnet.
Consulta los códigos de warm-up en [Referencia de códigos de error](/es/getnet-toolbox/sdk-white-label/reference-sdk/error-codes).
### Un pago es rechazado
El terminal lee la tarjeta con normalidad, pero el resultado es `33-` y aparece la pantalla "Pago rechazado".
**Causa.** El emisor rechazó la autorización: por ejemplo, fondos insuficientes, tarjeta bloqueada o tarjeta vencida. Esto depende del lado del titular de la tarjeta, no de una falla del terminal.
**Solución**
1. Pide al cliente otra tarjeta, o indícale que contacte a su banco.
2. Escala el caso solo si una tarjeta que el cliente considera válida falla en varios terminales.
### "Pago interrumpido" — error de servicio
Aparece la pantalla "Pago interrumpido" con un código `33-5xx` (por ejemplo, `33-500`, `33-503`, `33-504`).
**Causa.** El servicio de pagos falló o no estuvo disponible de forma temporal: una condición del lado del servidor o un tiempo de espera agotado.
**Solución**
1. No reintentes de inmediato.
2. Consulta la transacción por `paymentId` para confirmar si se procesó.
3. Si no se procesó, reintenta una vez después de una breve espera.
4. Si persiste o afecta a varios terminales, trátalo como un incidente de plataforma y contacta a Getnet.
### La tarjeta no se lee
El terminal repite "insertar, acercar o deslizar", o el contactless falla.
**Causa.** Falló una lectura contactless o por chip. Suele ser un fallback normal, no un error.
**Solución**
1. Pide al cliente que inserte el chip. Si el chip falla, pídele que deslice la banda magnética.
2. Si el terminal detecta varias tarjetas a la vez, pide al cliente que presente una sola, lejos de otras tarjetas o de la billetera.
3. Si una tarjeta específica falla con todos los métodos, pide otra tarjeta.
### Tiempo de espera agotado — no sabes si se cobró al cliente
El resultado es un tiempo de espera agotado (`33-504`) o la operación termina sin un resultado claro.
**Causa.** La respuesta no llegó dentro de la ventana de tiempo de espera, así que el resultado es desconocido: el cobro puede haberse completado o no.
**Solución**
1. No inicies todavía una nueva venta por el mismo monto.
2. Consulta la transacción por `paymentId` para confirmar si fue autorizada.
3. Inicia una nueva venta solo después de confirmar que la primera no se procesó.
### Un reembolso o una cancelación falla con "not found"
El reembolso devuelve un `33-404` con un mensaje "not found".
**Causa.** El `paymentId` o el entorno usado para el reembolso no coincide con la transacción original. Una referencia incorrecta es la causa más común.
**Solución**
1. Confirma el `paymentId` de la transacción original.
2. Confirma que estás ejecutando en el mismo entorno donde hiciste la venta.
3. Reintenta el reembolso con la referencia corregida.
### La transacción se reporta como duplicada o ya existente
El resultado indica que la transacción ya está en curso, ya se realizó o ya se canceló.
**Causa.** La operación ya se completó, o todavía está en proceso.
**Solución**
1. Revisa el recibo impreso o consulta el pago antes de actuar.
2. No repitas la operación hasta confirmar su estado real.
## Antes de contactar a Getnet
Algunas fallas requieren soporte de Getnet: configuración, autenticación, un `5xx` persistente, un terminal bloqueado o un error interno de EMV. Reúne esta información antes de contactarlos, para que soporte pueda localizar la transacción y reproducir el problema.
| Reúne | Detalle |
| :--- | :--- |
| Código de resultado | El `TransactionResult.result` completo (por ejemplo, `33-503`, `1-21`) y el mensaje en pantalla. |
| `error_code` / `reason_code` | En los errores de host, el `error_code` y el `reason_code` del payload de la respuesta (`details[]`). |
| `paymentId` | El `paymentId` (y el `orderId`, si existe) de la transacción afectada. |
| Terminal | El número de serie del terminal y el `terminalCode` configurado. |
| Entorno | Preproducción, homologación o producción: qué build ejecuta el dispositivo. |
| Fecha y hora | La fecha, la hora y la zona horaria del evento. |
| Alcance | Una tarjeta o terminal frente a varias: un caso aislado o uno generalizado. |
| Pasos para reproducir | Monto, medio de pago, marca de tarjeta y qué hizo el operador. |
## Siguientes pasos
* [Referencia de códigos de error](/es/getnet-toolbox/sdk-white-label/reference-sdk/error-codes) — el catálogo completo de códigos de host, de tarjeta y de warm-up.
* [Referencia del resultado de la transacción](/es/getnet-toolbox/sdk-white-label/reference-sdk/transaction-result) — los campos de resultado y los payloads que se devuelven a tu aplicación.
* [Referencia de inicialización](/es/getnet-toolbox/sdk-white-label/reference-sdk/initialization) — los estados del warm-up y cómo recuperarse de un `Failure`.
* [Registra telemetría](/es/getnet-toolbox/sdk-white-label/how-to-guides-sdk/record-telemetry) — registra tus propias entradas de diagnóstico para correlacionarlas con las trazas del SDK.