> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos, sintomas e ações

> Tabelas de HTTP, erros de refund, troubleshooting de integração (token, externalId, webhooks, QR, estados ambíguos).

## Formato de erro

As respostas de erro seguem o seguinte envelope:

```json theme={null}
{
    "code": "",
    "message": "bad_request: transaction.externalId is required",
    "status": 400
}
```

| Campo     | Descrição                                                                |
| --------- | ------------------------------------------------------------------------ |
| `code`    | Código de erro interno (quando disponível).                              |
| `message` | Mensagem legível descrevendo a causa — inclui o campo e a regra violada. |
| `status`  | Código HTTP repetido no corpo para conveniência.                         |

## Mapa geral (HTTP x ação)

| Status          | Causa provável                                   | Ação recomendada                                                    |
| --------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| `401`           | `Authorization` inválida ou vazia                | Reemitir/validar o token; checar `Bearer ` (espaço).                |
| `404`           | UUID errado ou escopo de organização (se houver) | Conferir `id` vindo do `201`; reexecutar a busca na mesma base URL. |
| `409`           | `externalId` duplicada                           | Trocar o identificador ou recuperar o registro existente.           |
| `422`           | Regra (prazo, status, teto)                      | Ajuste negócio; leia a mensagem do body.                            |
| `500` / timeout | Lado plataforma/rede                             | Backoff; anote `X-Correlation-ID` para suporte.                     |

## Refund-in (mensagens orientativas, origem)

| Situação            | Mensagem (referência)                                      |
| ------------------- | ---------------------------------------------------------- |
| Valor inválido      | `refundValue must be greater than zero`                    |
| Acima do disponível | `refundValue exceeds the amount available for refund`      |
| Prazo               | `refund deadline of 89 days has been exceeded`             |
| Cash-in não pago    | `refunds can only be issued for PAID cash-in transactions` |
| Não encontrado      | `original cash-in transaction not found`                   |

`TODO: códigos de erro` estruturados (ex.: `code`, `type`) além de `error` em string — a origem não fornece enumeração.

## Troubleshooting por sintoma

| Sintoma                                      | Causa provável                                                          | Ação                                                                                                        |
| -------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Token inválido**                           | Chave trocada, digitação incorreta ou ambiente (produção x homologação) | Reemitir, conferir header e host.                                                                           |
| **`externalId` duplicado**                   | Nova tentativa de cliente reenviou a mesma criação                      | Tornar criação idempotente; usar novo `externalId` por intenção distinta.                                   |
| **Transação não encontrada**                 | Path com id errado (confundir cash-in id x refund id)                   | Releia [identidade](/core-concepts/identity-model) — `refund-in` no path = **cash-in**.                     |
| **Webhook não recebido**                     | URL, TLS, 5xx no seu ponto de entrada, regras de rede                   | Ver logs de borda; testar o `GET /webhook` de cadastros; corrigir assinatura/timeout.                       |
| **Divergência** entre `GET` e último webhook | Atraso, reordenação, reentregas                                         | Deduplique; alinhe com consulta; ver [Divergência](/errors/error-handling#divergência-entre-webhook-e-get). |
| **Estado ambíguo**                           | `PROVIDER_RESULT_UNKNOWN` / `RECONCILIATION_REQUIRED`                   | [Reconciliação operacional](/guides/reconcile-transactions); escale se a operação estiver parada.           |
| **QR expirado**                              | Prazo de validade vencido                                               | Criar novo `POST /api/pix/cash-in` com novo QR.                                                             |
| **Refund rejeitado**                         | `FAILED` e regra de negócio                                             | Ajuste valor, prazo; cash-in ainda `PAID`.                                                                  |
| **Cash-out falhado**                         | `FAILED` / reserva `RELEASED`                                           | Não reenviar sem análise; conferir motivo e ledger.                                                         |
| **Cash-out revertido**                       | `REVERSED`                                                              | Ajuste saldo/ERP; [guia de reversão](/guides/handle-cash-out-reversal).                                     |

## Leitura

* [Tratamento de erros (visão)](/errors/error-handling)
* [FAQ](/faq/index)