> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goatpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Problemas comuns na integração com a API GoatPay

## 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$ 3,00; transferência: R$ 1,00 |

<h2 id="webhook-não-chega">
  Webhook não chega
</h2>

1. URL **HTTPS** em produção
2. Endpoint responde `2xx` dentro do timeout
3. Eventos inscritos (`payment.paid`, etc.)
4. Transação criada pela **mesma** API key do endpoint
5. Verifique entregas falhas em Integrações → Webhooks no dashboard

Tutorial: [Webhooks na prática](/pages/guides/webhooks-pratica).

## 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.paid` a polling agressivo
* QR expirado → `payment.pix.expired` ou status `CANCELED`
* 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 limiting](/api-reference/rate-limiting)

## Reembolso falha

Exige trilho **PADRAO** e depósito elegível com `endToEndId`. Use `transactionId` ou `e2eId` do depósito original.

## Integração com IA gerou código errado

* Aponte o assistente para [llms.txt](https://docs.goatpay.com.br/llms.txt) e [OpenAPI](https://docs.goatpay.com.br/openapi.yaml)
* Confirme que a rota está no [escopo v1](/api-reference/escopo-api-publica)
* [Guia de integração com IA](/pages/guides/integracao-ia)

## Ainda com problema

Abra ticket no dashboard com:

* `requestId` da resposta de erro
* Horário UTC aproximado
* Rota e método HTTP
* ID da transação GoatPay, se existir

Não envie `gp_live_` completo nem `whsec_` em tickets públicos.