# Códigos de Resposta e de Erro

Esta referência descreve os códigos de resposta e de erro usados pelas operações do POS Integrado. Todas as operações retornam pelo menos um **Code** numérico e uma **Message**.

## O que são códigos de resposta e de erro

Toda operação do POS Integrado retorna uma resposta com um **Code** numérico (Int) e uma **Message** (String).

> Todos os valores listados abaixo são retornados no mesmo campo `Code`. A categorização em "Códigos de Resposta" e "Códigos de Erro" existe somente para clareza da documentação e agrupamento lógico.

## Estrutura da resposta

Todas as operações retornam uma resposta estruturada contendo, no mínimo:

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `Code` | String | Código de resposta (veja a tabela abaixo). |
| `Message` | String | Resultado legível por humanos. |

Um código de resposta `0` indica sucesso.

## Códigos de resposta comuns

| Código | Descrição |
| :--- | :--- |
| 0 | Operação executada com sucesso |
| 1 | Operação negada |
| 2 | Operação cancelada pelo usuário |
| 3 | Erro encontrado durante o processamento da operação |
| 4 | Erro desconhecido – verifique os detalhes da mensagem |
| 5 | POS Integrado ainda no status WAITING_CONFIRMATION. Envie um comando Polling para iniciar. |
| 6 | Operação de cancelamento executada com sucesso |

<Callout type="note">

Os códigos `2` e `6` tratam de cancelamento, mas significam coisas diferentes. O `2` (**Operação cancelada pelo usuário**) é retornado por um comando — `Sale`, `Refund` ou `Pre-authorization` — que foi abortado. O `6` (**Operação de cancelamento executada com sucesso**) é retornado pelo próprio comando `Cancel`. Ambos valem para o modo SDK (USB / HTTP) e para o modo Cloud2Cloud.

</Callout>

<Callout type="note">

O código `5` indica que o terminal precisa restabelecer a conexão (por exemplo, após uma reinicialização ou queda do enlace). Execute o **Polling** novamente no mesmo Connector, reenvie os parâmetros de configuração e tente o comando outra vez. Consulte [Polling e reconexão](/pt/integrated-pos/core-concepts-pos/polling-reconnection).

</Callout>

<Callout type="note">

Quando `Code` é `3` para `Sale`, `Refund`, `Pre-authorization` ou `Shift`, o campo `Message` é uma string codificada em JSON que descreve as validações que falharam. Consulte [Erros de Validação](https://docs.globalgetnet.com/pt/products/in-store-payments/integrated-pos?doc=integrated-pos-validation-errors).

</Callout>

## Códigos de erro para o modo POS Integrado

Esses códigos geralmente aparecem em cenários de ativação, reconexão ou perda de conexão.

> A tabela abaixo lista todos os códigos de erro definidos no manual.

| Código | Descrição |
| :--- | :--- |
| `1-500` | O terminal não conseguiu inicializar corretamente as dependências para abrir a porta serial. |
| `1-501` | Problema de conectividade ao tentar configurar a conexão Wi-Fi. Verifique se o Wi-Fi está habilitado no terminal. |
| `1-502` | Erro ao tentar abrir a porta serial do terminal. |
| `1-503` | O usuário solicitou sair do Modo POS Integrado. |
| `A-503` | A conexão Wi-Fi ou USB foi finalizada inesperadamente enquanto a aplicação escutava os comandos. |
| `A-504` | O usuário está tentando sair do Modo POS Integrado, mas a aplicação não conseguiu encerrar a comunicação. |
| `A-505` | Uma desconexão de interface foi detectada e o Modo POS Integrado foi desconectado. |
| `G-XXXX` | Erros relacionados ao Provedor de Integração em Nuvem, como o G-Services. |
| `S-100` | Houve um erro interno no POS ou uma desconexão de interface, e a comunicação foi interrompida. |

<Callout type="warning">

Para códigos relacionados a conexão (por exemplo, A-503, A-504, A-505, S-100), siga o fluxo de reconexão descrito nos Conceitos Principais. Não presuma que o Connector continua válido.

</Callout>

## Códigos de status de transação

Retornados no campo `Status` de uma resposta de `CheckStatus`. Eles descrevem o estado de uma transação anterior, não o resultado do próprio comando `CheckStatus` — esse resultado fica em `Code`.

| Código de status | Nome do status | Descrição |
| :--- | :--- | :--- |
| **0** | `APPROVED` | Transação capturada. Usado para vendas com cartão padrão e QR Code com cartão. |
| **1** | `AUTHORIZED` | Transação autorizada (pré-autorização ou QR PCT). |
| **2** | `REFUNDED` | Transação reembolsada (D+1). |
| **3** | `CANCELED` | Transação cancelada (D+0). |
| **4** | `REVERSED` | Transação revertida (desfeita). |
| **5** | `NOT_FOUND` | Nenhuma transação encontrada para o `CallerId` informado. |
| **6** | `UNKNOWN` | Status não mapeado. |

Os meios de pagamento por QR Code se comportam de forma diferente. Transações **QR PCT** (Point of Capture) sempre retornam `AUTHORIZED` e nunca `APPROVED`. O **QR Code com cartão** segue o mesmo comportamento de uma venda com cartão padrão.

## Diretrizes de tratamento de erros

* Sempre verifique o **Code** da resposta antes de prosseguir (por exemplo, `0` = sucesso).
* Não repita operações às cegas; revalide o estado do terminal com **Polling** após erros.
* Para o código `5`, envie um comando **Polling** antes de continuar.
* Para erros relacionados a conexão, siga as instruções de reconexão nesta documentação.

## Recursos relacionados

* [Polling e reconexão](/pt/integrated-pos/core-concepts-pos/polling-reconnection) — Quando fazer o polling e como recuperar.