Formato de erro
As respostas de erro seguem o seguinte envelope:{
"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 — 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. |
| Estado ambíguo | PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIRED | Reconciliação operacional; 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. |