> ## 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. # Troubleshooting > Diagnóstico passo a passo para os problemas mais comuns: token, payload, externalId, webhook, assinatura, QR, refund e estados ambíguos. ## Token inválido ou ausente **Sintoma:** `401 Unauthorized` em qualquer chamada. | Verificação | Ação | | ---------------------------------------------------- | -------------------------------------------------------------- | | Header `Authorization` presente? | Adicionar: `Authorization: Bearer ` | | Prefixo `Bearer ` com espaço? | Corrigir: `Bearer ` (com espaço após) | | Token correto para o ambiente? | Confirmar base URL e token (produção ≠ sandbox) | | Token expirado ou revogado? | Reemitir via `POST /api-key/generate` com token administrativo | | Token administrativo correto em `/api-key/generate`? | Validar com a equipe de plataforma | *** ## Payload inválido (400 / 422) **Sintoma:** `400 Bad Request` ou `422 Unprocessable Entity`. | Verificação | Ação | | ----------------------------------------------- | -------------------------------------------------------- | | `Content-Type: application/json` presente? | Adicionar em todos os `POST` com corpo | | JSON malformado? | Validar com `jq` ou ferramenta online | | Campos obrigatórios ausentes? | Revisar a referência do endpoint | | `value` ou `refundValue` em BRL (não centavos)? | Corrigir: campos de request são em reais (ex.: `150.75`) | | `pixKeyType` coerente com `pixKey`? | Ex.: `email` deve ter formato `a@b.com` | *** ## `externalId` duplicado (409) **Sintoma:** `409 Conflict`. | Verificação | Ação | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Mesma criação sendo reenviada? | Buscar o recurso existente pelo `externalId` (se houver endpoint) ou pelo `id` persistido | | Lógica de retry sem novo `externalId`? | Usar novo `externalId` apenas para **nova intenção** de operação, não para retry da mesma | | `externalId` sendo reutilizado entre operações distintas? | `externalId` deve ser único por operação | *** ## Transação não encontrada (404) **Sintoma:** `404 Not Found` em `GET /api/pix/cash-in/{id}` ou similar. | Verificação | Ação | | ----------------------------------------------- | --------------------------------------------------------------------- | | UUID correto? | Conferir o `id` retornado no `201` da criação | | Confundindo `id` do cash-in com `id` do refund? | Leia [modelo de identidade](/core-concepts/identity-model) | | Usando `transactionId` do BaaS em vez do UUID? | `GET /api/pix/cash-in/{id}` usa o UUID interno, não o `transactionId` | | Ambiente correto? | Produção vs. sandbox: base URLs distintas | *** ## Webhook não recebido **Sintoma:** pagamento confirmado (via GET), mas nenhum webhook chegou. `GET /webhook` — confirmar que a URL está registrada e correta. Testar a URL com uma requisição manual (`curl -X POST https://seu-sistema.com/webhooks/pix -H "Content-Type: application/json" -d '{}'`) — deve retornar 2xx (mesmo sem assinatura válida, o endpoint deve estar acessível). Certificado público válido, sem autoassinado, na URL registrada. Logs do seu endpoint de webhook para o período — possível 5xx que gerou retentativas sem sucesso. Regras de WAF podem bloquear headers como `Digital-Signature`. Permitir passagem desse header. Se o pagamento já está `PAID` na consulta, o estado real está correto. Reconciliar localmente e investigar a entrega em segundo plano. *** ## Assinatura inválida **Sintoma:** verificação de `Digital-Signature` sempre falha. | Verificação | Ação | | ------------------------------------------- | ----------------------------------------------------------------- | | Raw body preservado? | Salvar o buffer antes do parse JSON; middlewares podem modificar | | Chave pública desatualizada? | Buscar novamente via `GET /public-key`; cache pode estar expirado | | Encoding Base64 correto? | Sem espaços ou quebras de linha na string da assinatura | | Algoritmo correto? | ECDSA P-256 + SHA-256 sobre o body bruto | | Formato da assinatura (DER vs. IEEE P1363)? | `TODO: confirmar com a plataforma o encoding exato` | *** ## QR Code expirado **Sintoma:** pagador informa que o QR não funciona ou o cash-in está `EXPIRED`. | Verificação | Ação | | ---------------------------------------- | ------------------------------------------------------------------- | | `expirationDate` da cobrança verificado? | Comparar com o horário atual em UTC | | Cobrança expirada? | Criar nova cobrança com `POST /api/pix/cash-in` e novo `externalId` | | `expirationTime` muito curto? | Aumentar o valor em segundos na criação | *** ## Refund rejeitado **Sintoma:** `422` ao tentar criar refund-in. | Mensagem | Causa | Ação | | ---------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------- | | `refundValue must be greater than zero` | Valor zerado ou negativo | Corrigir o valor | | `refundValue exceeds the amount available for refund` | Teto atingido (pending + confirmed) | Reduzir o valor ou aguardar devoluções pendentes serem resolvidas | | `refund deadline of 89 days has been exceeded` | Prazo regulatório | Não é possível devolver; encerrar o processo | | `refunds can only be issued for PAID cash-in transactions` | Cash-in não está `PAID` | Verificar status com `GET /api/pix/cash-in/{id}` | | `original cash-in transaction not found` | UUID errado no path | Usar o `id` do cash-in, não o `transactionId` | *** ## Estado ambíguo (PROVIDER\_RESULT\_UNKNOWN / RECONCILIATION\_REQUIRED) **Sintoma:** transação presa sem avançar para estado terminal. | Estado | Ação imediata | Próxima ação | | ------------------------- | ----------------------------------------------------- | --------------------------------------------- | | `PROVIDER_RESULT_UNKNOWN` | Monitorar com `GET` a cada 60s | Após 15min sem resolução: escalar | | `RECONCILIATION_REQUIRED` | Abrir ticket de suporte com `id` e `X-Correlation-ID` | Aguardar resolução; não concluir internamente | Veja [Reconciliação](/ledger-and-reconciliation/reconciliation) para o fluxo completo. *** ## Cash-out falhado inesperadamente **Sintoma:** cash-out vai a `FAILED` sem causa aparente. | Verificação | Ação | | --------------------------------- | ---------------------------------------------------------- | | Saldo suficiente na conta? | Consultar ledger e saldo disponível | | Chave Pix do destinatário válida? | Verificar formato e tipo em `pixKey`/`pixKeyType` | | BaaS rejeitou por regra interna? | Consultar mensagem de erro no `GET /api/pix/cash-out/{id}` | | Reserva foi liberada? | Status `RELEASED` confirma liberação; saldo retornou | *** ## Inconsistência entre consulta e notificação **Sintoma:** GET retorna `CONFIRMED` mas o webhook diz `FAILED` (ou vice-versa). **Regra:** `GET /.../{id}` é o dado mais recente e **autoritativo**. Webhooks são at-least-once e podem chegar fora de ordem. | Situação | Ação | | ----------------------------- | --------------------------------------------------------------- | | GET mais avançado que webhook | Confiar no GET; webhook estava atrasado ou desordenado | | Webhook mais avançado que GET | Aguardar consistência eventual (segundos) e consultar novamente | | Discordância persistente | Abrir ticket com ambos os dados para análise | *** ## Referências * [Tratamento de erros](/errors/error-handling) * [Códigos e sintomas](/errors/error-codes) * [Reconciliação](/ledger-and-reconciliation/reconciliation) * [Modelo de identidade](/core-concepts/identity-model) * [FAQ](/faq/index)