401 Unauthorized
| Causa | Solução |
|---|---|
| Header ausente | Envie X-API-Key: gp_live_... |
| Chave revogada | Crie nova chave no dashboard |
| Espaços ou quebra de linha na chave | Copie do secret em variável de ambiente |
403 Forbidden
| Causa | Solução |
|---|---|
| Permissão ausente na chave | Ajuste em Integrações → Chaves de API |
| IP bloqueado | Adicione IP/CIDR na chave ou allowAnyIp: true |
| Conta não verificada | Conclua KYC para liberar recursos do trilho PADRAO |
| Subcontas não habilitadas | Solicite acesso via dashboard |
400 Saldo ou transferência
| Mensagem típica | Solução |
|---|---|
| Saldo insuficiente | GET /account/balance → availableAmount |
| Pendências somadas | Aguarde saques PROCESSING |
| Valor mínimo | Cobrança PADRAO: mín. R 1,00 |
Webhook não chega
- URL HTTPS em produção
- Endpoint responde
2xxdentro do timeout - Eventos inscritos (
payment.paid, etc.) - Transação criada pela mesma API key do endpoint
- Verifique entregas falhas em Integrações → Webhooks no dashboard
Assinatura HMAC inválida
- Calcule HMAC sobre o raw body (bytes exatos)
- Use o
whsec_...da criação do endpoint - Header:
x-goatpay-signature: sha256=<hex> - Não re-serialize JSON antes de validar
QR PIX não confirma
- Prefira webhook
payment.paida polling agressivo - QR expirado →
payment.pix.expiredou statusCANCELED - Confirme trilho da chave compatível com a cobrança
429 Rate limit
100 requisições por minuto por chave. Backoff exponencial. Webhooks > polling. Rate limitingReembolso falha
Exige trilho PADRAO e depósito elegível comendToEndId. Use transactionId ou e2eId do depósito original.
Integração com IA gerou código errado
- Aponte o assistente para llms.txt e OpenAPI
- Confirme que a rota está no escopo v1
- Guia de integração com IA
Ainda com problema
Abra ticket no dashboard com:requestIdda resposta de erro- Horário UTC aproximado
- Rota e método HTTP
- ID da transação GoatPay, se existir
gp_live_ completo nem whsec_ em tickets públicos.