# Códigos de respuesta y error

Esta referencia describe los códigos de respuesta y error que usan las operaciones del TPV Integrado. Todas las operaciones devuelven al menos un **Code** numérico y un **Message**.

## ¿Qué son los códigos de respuesta y error?

Todas las operaciones del TPV Integrado devuelven una respuesta con un **Code** numérico (Int) y un **Message** (String).

> Todos los valores que se listan a continuación se devuelven en el mismo campo `Code`. La categorización en "Códigos de respuesta" y "Códigos de error" existe solo para dar claridad a la documentación y crear agrupaciones lógicas.

## Estructura de la respuesta

Todas las operaciones devuelven una respuesta estructurada que contiene como mínimo:

| Campo | Tipo | Descripción |
| :--- | :--- | :--- |
| `Code` | String | Código de respuesta (consulta la tabla a continuación). |
| `Message` | String | Resultado legible por humanos. |

Un código de respuesta `0` indica éxito.

## Códigos de respuesta comunes

| Código | Descripción |
| :--- | :--- |
| 0 | Operación ejecutada con éxito |
| 1 | Operación denegada |
| 2 | Operación cancelada por el usuario |
| 3 | Se encontró un error durante el procesamiento de la operación |
| 4 | Error desconocido: revisa los detalles del mensaje |
| 5 | TPV Integrado aún en estado WAITING_CONFIRMATION. Envía un comando Polling para iniciar. |
| 6 | Operación de cancelación ejecutada con éxito |

<Callout type="note">

Los códigos `2` y `6` se relacionan con la cancelación, pero significan cosas distintas. El código `2` (**Operación cancelada por el usuario**) lo devuelve un comando abortado: `Sale`, `Refund` o `Pre-authorization`. El código `6` (**Operación de cancelación ejecutada con éxito**) lo devuelve el propio comando `Cancel`. Ambos se aplican a los modos SDK (USB / HTTP) y Cloud2Cloud.

</Callout>

<Callout type="note">

El código `5` indica que el terminal debe restablecer su conexión, por ejemplo después de un reinicio o de una caída del enlace. Ejecuta **Polling** de nuevo en el mismo Connector, reenvía los parámetros de configuración y reintenta el comando. Consulta [Polling y reconexión](/es/integrated-pos/core-concepts-pos/polling-reconnection).

</Callout>

<Callout type="note">

Cuando `Code` es `3` para `Sale`, `Refund`, `Pre-authorization` o `Shift`, el campo `Message` es una cadena codificada en JSON que describe las validaciones fallidas. Consulta [Errores de validación](https://docs.globalgetnet.com/es/products/in-store-payments/integrated-pos?doc=integrated-pos-validation-errors).

</Callout>

## Códigos de error para el Modo TPV Integrado

Estos códigos aparecen normalmente en escenarios de activación, reconexión o pérdida de conexión.

> La siguiente tabla lista todos los códigos de error definidos en el manual.

| Código | Descripción |
| :--- | :--- |
| `1-500` | El terminal no pudo inicializar las dependencias necesarias para abrir el puerto serie. |
| `1-501` | Problema de conectividad al intentar configurar la conexión Wi-Fi. Verifica si el Wi-Fi está habilitado en el terminal. |
| `1-502` | Error al intentar abrir el puerto serie del terminal. |
| `1-503` | El usuario solicitó salir del Modo TPV Integrado. |
| `A-503` | La conexión Wi-Fi o USB finaliza de forma inesperada mientras la aplicación está escuchando comandos. |
| `A-504` | El usuario intenta salir del Modo TPV Integrado, pero la aplicación no pudo cerrar la comunicación. |
| `A-505` | Se detectó una desconexión de la interfaz y el Modo TPV Integrado se desconectó. |
| `G-XXXX` | Errores relacionados con el proveedor de integración en la nube, como G-Services. |
| `S-100` | Hubo un error interno en el TPV o una desconexión de la interfaz y la comunicación se interrumpió. |

<Callout type="warning">

Para los códigos relacionados con la conexión (por ejemplo, A-503, A-504, A-505, S-100), sigue el flujo de reconexión descrito en los Conceptos básicos. No asumas que el Connector sigue siendo válido.

</Callout>

## Códigos de estado de transacción

Se devuelven en el campo `Status` de una respuesta de `CheckStatus`. Describen el estado de una transacción pasada, no el resultado del propio comando `CheckStatus`; ese resultado está en `Code`.

| Código de estado | Nombre del estado | Descripción |
| :--- | :--- | :--- |
| **0** | `APPROVED` | Transacción capturada. Se usa para ventas con tarjeta estándar y para QR Code con tarjeta. |
| **1** | `AUTHORIZED` | Transacción autorizada (preautorización o QR PCT). |
| **2** | `REFUNDED` | Transacción reembolsada (D+1). |
| **3** | `CANCELED` | Transacción cancelada (D+0). |
| **4** | `REVERSED` | Transacción revertida (deshecha). |
| **5** | `NOT_FOUND` | No se encontró ninguna transacción para el `CallerId` indicado. |
| **6** | `UNKNOWN` | Estado no mapeado. |

Los métodos de pago con QR Code se comportan de forma distinta. Las transacciones **QR PCT** (Point of Capture) siempre devuelven `AUTHORIZED` y nunca `APPROVED`. **QR Code con tarjeta** sigue el mismo comportamiento que una venta con tarjeta estándar.

## Pautas para el manejo de errores

* Verifica siempre el **Code** de la respuesta antes de continuar (por ejemplo, `0` = éxito).
* No reintentes operaciones a ciegas; revalida el estado del terminal con **Polling** después de un error.
* Para el código `5`, envía un comando **Polling** antes de continuar.
* Para los errores relacionados con la conexión, sigue las instrucciones de reconexión de esta documentación.

## Recursos relacionados

* [Polling y reconexión](/es/integrated-pos/core-concepts-pos/polling-reconnection) — cuándo hacer polling y cómo recuperarte.