Troubleshooting

401 em toda chamada

• Header errado: é X-API-Key, não Authorization.
• Espaço ou quebra de linha grudados na chave ao copiar.
• Chave de teste usada onde você esperava dinheiro real: ela opera no sandbox, sem mover dinheiro. Confira o rótulo da chave no painel.
• Chave revogada no painel.

403 em uma rota específica

A chave é válida, mas não tem permissão para aquela operação. Ajuste as permissões da chave no painel — não crie uma chave nova por causa disso.

Webhook não chega

1. A URL é pública?

   Túnel de desenvolvimento fechado ou endereço de rede interna não recebem nada.

2. O endpoint responde 200 rápido?

   Se o processamento demora, a entrega vira timeout e retentativa.

3. O ambiente bate?

   Eventos do sandbox chegam nos mesmos endpoints, marcados com livemode: false. Se um evento não chegou, veja se a cobrança foi criada com a chave do ambiente que você está olhando.

4. Tem algo na frente do endpoint?

   Firewall, WAF ou proteção anti-bot podem barrar a entrega antes de ela chegar no seu código.

Assinatura do webhook nunca bate

Quase sempre é o corpo: a validação precisa usar o texto cru recebido. Qualquer JSON.parse seguido de JSON.stringify muda os bytes e invalida o HMAC. Ver Webhooks.

Cobrança duplicada

Criação sem idempotency_key combinada com retentativa automática. Derive a chave do ID do pedido e o problema some.

429 constante

Troque polling por webhook e mande trabalho em lote para uma fila com concorrência limitada. Ver Limite de requisições.

Valor errado no extrato

Provável conversão de centavos para real em algum ponto do caminho, ou uso de float. Mantenha inteiro do começo ao fim e formate só na exibição.

Nada disso resolveu

Abra um chamado com o request_id da chamada, o horário e o que você esperava que acontecesse. Sem request_id, o diagnóstico fica no chute. Nunca envie a sua chave de API no chamado.