> ## 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.

# Tratamento de erros

> Envelope, HTTP, retentativas, divergência webhook vs. GET e o que fazer com estados ambíguos.

## Envelope (típico)

```json theme={null}
{
  "error": "descrição",
  "status": 400
}
```

`TODO: chaves adicionais` (código, `correlation_id`) se existirem na implementação — a origem mostra o mínimo.

## Códigos HTTP (mapa geral)

| Código | Significado                                                       | Ação                                                 |
| ------ | ----------------------------------------------------------------- | ---------------------------------------------------- |
| `200`  | Sucesso em leitura / confirmação de webhook de entrada (parceiro) | Siga a operação.                                     |
| `201`  | Criação de recurso                                                | Guarde o `id` e `externalId`.                        |
| `400`  | Validação de payload                                              | Corrija o corpo.                                     |
| `401`  | Autenticação                                                      | Conferir `Bearer` e validade/escopo do token.        |
| `404`  | Não encontrado                                                    | Conferir parâmetros, ambiente e o UUID usado.        |
| `409`  | Conflito (ex.: `externalId` duplicado)                            | Outro `externalId` ou recuperar o recurso existente. |
| `422`  | Regra de negócio                                                  | Ajuste valor, prazo ou pré-condições.                |
| `500`  | Erro interno                                                      | [Retentativas](#retentativas) (com cuidado).         |

Tabela de troubleshooting: [Códigos e sintomas](/errors/error-codes).

## Retentativas

* **5xx** ou **timeout** em leitura (`GET`) ou leitura semelhante: use **backoff exponencial** com teto, sem martelar a API.
* **4xx** (fora de rate limit) em escrita: **não** retente sem corrigir o payload.

`TODO: rate limit` (`429`, `Retry-After`) — a origem não cita; confirmar com a implementação do gateway.

<h2 id="divergencia-entre-webhook-e-get">
  Divergência entre webhook e `GET /.../{id}`
</h2>

1. Trate o webhook como **at-least-once**; valide a assinatura e deduplique.
2. Se a consulta mostrar o estado “à frente” do último evento processado, use o **estado idempotente** e reconcile logs.
3. Em `PROVIDER_RESULT_UNKNOWN` ou `RECONCILIATION_REQUIRED`, use o [guia de reconciliação operacional](/guides/reconcile-transactions).

## Falhas do seu endpoint de notificação

* Após [validar a assinatura](/guides/verify-webhook-signatures), responda **2xx** rapidamente. Erros **5xx** do seu lado alimentam retentativas com **backoff** (fila, conforme a origem).
* Handlers devem ser **idempotentes**.

## Dados pessoais (LGPD)

O documento de origem cita: documentos podem ser **mascarados** em respostas de detalhe. Evite registrar dados sensíveis indevidamente.

## Ver também

* [Convenções de HTTP](/getting-started/environments-and-headers)
* [Webhooks e assinatura](/webhooks/clearpago-to-merchant)