# Códigos de respuesta y errores

El Get Mini Android SDK utiliza un sistema de errores estructurado para distinguir entre operaciones exitosas, cancelaciones de usuario, fallos técnicos y denegaciones financieras. Comprender estos códigos de respuesta y categorías de error te ayudará a implementar una gestión de errores adecuada y a proporcionar información clara a los usuarios.

## Tipos de respuesta RepositoryResult

Todas las operaciones del SDK devuelven resultados envueltos en la clase sellada `RepositoryResult`. El tipo de resultado indica el desenlace de alto nivel de la operativa.

| Tipo de Resultado | Descripción | Cuándo ocurre |
| :---- | :---- | :---- |
| `RepositoryResult.Success` | La operación se completó con éxito con datos de resultado | Transacción aprobada, inicialización exitosa, dispositivo conectado |
| `RepositoryResult.Error` | La operación falló debido a un error técnico o fallo de validación | Error de red, PIN pad desconectado, parámetros inválidos, tiempo de espera agotado |
| `RepositoryResult.Cancelled` | El usuario canceló la operación | El cliente pulsó cancelar en el PIN pad, el usuario salió de la pantalla de pago |

Verifica primero el tipo de resultado antes de acceder a los datos o mensajes de error para garantizar la seguridad de tipos en tu implementación.

## Tipos de PaymentResult

Específicamente para las operaciones de pago, los resultados exitosos (`RepositoryResult.Success`) contienen un `PaymentResult` que indica el resultado de la transacción.

| Resultado de Pago | Descripción | Próximos pasos |
| :---- | :---- | :---- |
| `PaymentResult.Accepted` | Transacción autorizada y aprobada por el host de pagos | Guarda el código de autorización y el ID de operación, proporciona el recibo |
| `PaymentResult.Denied` | Transacción denegada por el host de pagos o el emisor | Muestra el motivo de la denegación al cliente, ofrece otro método de pago |

Las denegaciones de pago se consideran operaciones del SDK "exitosas" (la comunicación se realizó correctamente) pero representan rechazos a nivel de negocio por parte del host de pagos.

## Códigos de respuesta de autorización

Cuando una transacción es denegada (`PaymentResult.Denied`), el campo `responseCode` contiene un código del host de autorización de pagos que indica el motivo específico de la denegación.

### Códigos de éxito

| Rango de Código | Significado | Descripción |
| :---- | :---- | :---- |
| 0000-0099 | Aprobada | Transacción autorizada con éxito. Proceder con el pedido. |

### Problemas con la tarjeta

| Código | Significado | Acción recomendada |
| :---- | :---- | :---- |
| 0101 | Tarjeta Caducada | Solicita otro método de pago. La fecha de caducidad ha pasado. |
| 0102 | Tarjeta Bloqueada | Indica al cliente que contacte con su banco. La tarjeta está bloqueada. |
| 0106 | Intentos de PIN excedidos | Tarjeta bloqueada por PIN incorrecto. El cliente debe contactar con su banco. |
| 0202 | Tarjeta Restringida | La tarjeta tiene restricciones para este tipo de pago. Solicita otra tarjeta. |

### Fondos insuficientes

| Código | Significado | Acción recomendada |
| :---- | :---- | :---- |
| 0180 | Fondos Insuficientes | No hay suficiente saldo o crédito. Solicita otro método de pago. |
| 0184 | Límite de Tarjeta Excedido| El importe excede el límite de la tarjeta. Prueba con un importe menor. |

### Problemas de transacción

| Código | Significado | Acción recomendada |
| :---- | :---- | :---- |
| 0190 | Denegación General | El emisor denegó sin motivo específico. Solicita otro método de pago. |
| 0912 | Emisor no Disponible | No se puede contactar con el banco emisor. Reintenta más tarde. |
| 9102 | Transacción Inválida | Parámetros inválidos o no soportados. Verifica importe y configuración. |

### Errores de autenticación

| Código | Significado | Acción recomendada |
| :---- | :---- | :---- |
| 0184 | Error de PIN | PIN introducido incorrecto. Permite al cliente reintentar. |
| 0191 | Autenticación Fallida | Fallo en la autenticación de la transacción. Solicita otro método. |

<Callout type="note">

Los códigos de respuesta pueden variar según el procesador de pagos y la configuración del adquiriente. Consulta con el soporte de Get Mini para mapeos específicos.

</Callout>

## Mensajes de error técnicos del SDK

| Código | Identificador | Causa | Descripción / Resolución |
| :---- | :---- | :---- | :---- |
| `1004` | `noInternetConnection` | Sin conectividad a internet | Verifica que el dispositivo tenga una conexión a internet activa. |
| `1005` | `unrealizedOperation` | Operación no realizada | Fallo general indicando que la operativa no se completó. |
| `1006` | `transactionDeniedInPinPad` | Denegación offline EMV | La transacción fue denegada localmente por el chip de la tarjeta. |
| `1007` | `signatureTooBig` | Firma demasiado grande | La imagen de la firma capturada excede el límite de 4999 bytes. |
| `1008` | `genericError` | Error genérico | Fallo general; revisa los datos de la petición y los logs. |
| `1009` | `communicationWithPinPadFailed` | Conexión con PIN pad perdida | Se perdió la conexión Bluetooth con el PIN pad Get Mini. |
| `1010` | `communicationWithWebServiceFailed`| Conectividad Web Service | Fallo al comunicar con el host de pagos o servidores de proceso. |
| `1011` | `malformedPinPadResponse` | Respuesta PIN pad malformada | La respuesta recibida del PIN pad es técnicamente incorrecta. |
| `1012` | `malformedPinPadConfirmation`| Confirmación malformada | El mensaje de confirmación del PIN pad es incorrecto. |
| `1013` | `unInitializedPinPad` | PIN pad no inicializado | Llama a `inicializarPinpad()` antes de procesar cualquier pago. |
| `1014` | `incorrectSignatureValidation` | Fallo de integridad | Falló la validación de integridad de la respuesta del host. |
| `1015` | `invalidSelectionDccCurrency` | Error de moneda DCC | La selección de moneda para la conversión DCC no es válida. |
| `1016` | `unInitializedPinpadByFailedUpdate`| Fallo de carga parámetros | No se pudieron cargar parámetros durante la inicialización. |
| `1017` | `unInitializedPinpadByFailedTDES` | Fallo de carga TDES | No se pudieron cargar las claves de seguridad durante la inicialización. |
| `1018` | `pinpadInitializationNotFinished` | Inicialización parcial | El proceso de inicialización del PIN pad no se completó. |
| `1019` | `pinpadWithOutKeys` | Faltan claves simétricas | El terminal no está operativo porque faltan sus claves internas. |
| `1020` | `invalidPUPVersion` | Versión protocolo errónea | Versión de protocolo del PIN pad incompatible con esta versión del SDK. |
| `1021` | `serverResponseWithError` | Respuesta error servidor | El servidor de pagos devolvió un error estructurado; revisa los datos. |
| `1022` | `invalidTerminalForOperation` | Estado terminal inválido | El terminal seleccionado no es válido para la operativa solicitada. |
| `1023` | `terminalWithoutPermissionForOperation` | Permiso denegado | La cuenta/terminal no tiene permiso para esta funcionalidad. |
| `1024` | `creditCardNotValid` | Lectura tarjeta inválida | La tarjeta presentada no es válida o no puede ser procesada. |
| `1025` | `misApplication` | Error de aplicación | Aplicación incorrecta seleccionada durante la lectura de la tarjeta. |
| `1026` | `misCodeDeferPayment` | Código de aplazamiento inválido | El código de aplazamiento de la operación no es válido. |
| `1027` | `rejectedSWAutoDownload` | Telecarga rechazada | Solicitud de telecarga rechazada. |
| `1028` | `rejectedSWAutoDownloadByTimeout` | Timeout en telecarga | Se recibe un timeout o un error de transmisión al enviar un bloque de software. |
| `117` | `pinIncorrecto` | PIN incorrecto | El cliente introdujo un PIN incorrecto durante la autorización online. |
| `195` | `repetirLectura` | Repetir lectura tarjeta | Indica al usuario que repita la lectura (Chip o doble Tap). |
| `196` | `pinTitular` | PIN requerido | Solicita el PIN al titular de la tarjeta. |
| `1055` | `noManualEntryEnabled` | Entrada manual deshabilitada| El comercio no está configurado para permitir entrada manual de tarjeta. |
| `1057` | `operationNotFound` | Operación no encontrada | No se puede realizar una acción sobre una transacción inexistente. |

Registra siempre los mensajes de error para depuración y soporte, mostrando alternativas amigables a los clientes.

## Errores específicos del PIN pad

Errores adicionales específicos de la operativa con el PIN pad Bluetooth y gestión de periféricos.

| Tipo de Error | Descripción | Resolución |
| :---- | :---- | :---- |
| Fallo de Emparejamiento | No se puede conectar por Bluetooth | Verifica el modo emparejamiento y que el Bluetooth esté activo. |
| Batería Crítica | Batería del PIN pad muy baja | Carga el dispositivo PIN pad antes de intentar transacciones. |
| Firmware Incompatible | Versión de firmware no soportada | Actualiza el firmware a través de las herramientas de soporte. |
| Dispositivo Ocupado | PIN pad procesando otra acción | Espera a que la operativa actual termine antes de iniciar otra. |

## Códigos de denegación offline (EMV)

Cuando una transacción es denegada localmente por el chip de la tarjeta sin consultar online, se pueden devolver los siguientes códigos:

| Código | Identificador Técnico | Descripción |
| :---- | :---- | :---- |
| `0` | `DENEGADA_OFF_IMPORTE_O` | Importe menor o igual a cero. |
| `-1` | `DENEGADA_OFF_PAIS_O_MONEDA_EXTRANJERO` | Moneda/país extranjero no permitido offline. |
| `-2` | `DENEGADA_OFF_BLOQUE_PIN` | Tarjeta bloqueada por intentos de PIN. |
| `-3` | `DENEGADA_OFF_LIMITE_IMPORTE_SUPERADO` | Importe excede el límite offline permitido. |
| `-4` | `DENEGADA_OFF_LIMITE_OPERACIONES_SUPERADO`| Número de transacciones offline excedido. |
| `-5` | `DENEGADA_OFF_OPERACION_BANDA_NO_PERMITIDA` | Banda magnética no permitida offline. |
| `-6` | `DENEGADA_OFF_OPERACION_ENTRADA_MANUAL_NO_PERMITIDA` | Entrada manual no permitida offline. |
| `-7` | `DENEGADA_OFF_TARJETA_CADUCADA` | Tarjeta caducada. |
| `-8` | `DENEGADA_APLICACION_NO_PERMITIDA` | Aplicación (AID) no permitida. |
| `-9` | `DENEGADA_OPERACION_NO_PERMITIDA` | Tipo de lectura no reconocido. |
| `-10` | `DENEGADA_9F27` | Tipo de transacción 9F27 denegado por la tarjeta. |
| `-11` | `DENEGADA_TARJETA_PRIVADA` | Tarjeta privada/no financiera no permitida. |
| `-12` | `DENEGADA_OPERACION_MOVIL_NO_AUTENTICADA` | Pago móvil sin autenticación. |
| `-13` | `DENEGADA_OPERACION_CONTACTLESS_NO_AUTENTICADA` | Autenticación de operativa contactless no realizada. |
| `-14` | `DENEGADA_OFF_LIMITE_IMPORTE_ACUMULADO_SUPERADO` | Límite de importe acumulado offline excedido. |
| `-15` | `DENEGADA_OFF_LIMITE_OPERACIONES_ACUMULADAS_SUPERADO` | Límite de operaciones offline acumuladas superado. |
| `-16` | `DENEGADA_PIN_OFF_EXCEDIDO` | Intentos de PIN offline excedidos. |
| `-17` | `DENEGADA_BYPASS_PIN` | PIN requerido pero no hay PIN pad disponible. |
| `-18` | `DENEGADA_SDA_FALLIDA` | Validación SDA (Static Data Authentication) fallida. |
| `-19` | `DENEGADA_DDA_FALLIDA` | — |
| `-20` | `DENEGADA_APP_CADUCADA` | — |
| `-21` | `DENEGADA_APP_NO_EFECTIVA` | — |
| `-22` | `DENEGADA_SERV_NO_PERMITIDO` | — |
| `-23` | `DENEGADA_VERIF_ERR_TITULAR` | — |
| `-24` | `DENEGADA_PIN_NO_PINPAD` | — |
| `-25` | `DENEGADA_FALLBACK` | Fallback no soportado. |

## Buenas prácticas en gestión de errores

Al procesar errores, considera la categoría para proporcionar la mejor experiencia al usuario:

**Errores Técnicos (RepositoryResult.Error)**: Registra información detallada para depuración. Muestra mensajes genéricos y amigables a los clientes sin exponer detalles técnicos. Ofrece reintento para fallos transitorios como problemas de red.

**Denegaciones de Pago (PaymentResult.Denied)**: Muestra el motivo de la denegación de la respuesta de autorización. Guía a los clientes hacia métodos de pago alternativos. Nunca reintentes automáticamente sin acción del cliente.

**Cancelaciones de Usuario (RepositoryResult.Cancelled)**: Gestiona de forma fluida sin mensajes de error. Permite a los clientes reintentar o elegir otras acciones. Registra las cancelaciones para análisis de negocio.