Troubleshooting

Resolução de problemas comuns, códigos de erro e boas práticas.

1. Códigos de Erro HTTP

Status	Significado	Causa Comum	Solução
400	Bad Request	Parâmetros inválidos	Verifique o formato dos dados enviados
401	Unauthorized	Token inválido ou ausente	Verifique o header Authorization
403	Forbidden	Sem permissão	Verifique as permissões do token
404	Not Found	Recurso não encontrado	Verifique o ID ou URL
422	Unprocessable	Validação falhou	Verifique os campos obrigatórios
429	Too Many Requests	Rate limit excedido	Aguarde e tente novamente
500	Internal Error	Erro no servidor	Contate o suporte

2. Problemas Comuns

Verificações:

O token está no header correto? Authorization: Bearer {token}
O token foi copiado completo? (sem espaços extras)
O token está ativo? (verifique no painel)
O token tem as permissões necessárias?

Verificações:

A URL está correta e acessível?
O servidor responde com status 200?
O firewall permite requisições da AjnaPay?
Verifique os logs do seu servidor
Teste com webhook.site para debug

Verificações:

O pagamento foi confirmado? (status: completed)
Os splits estão configurados corretamente?
A conta está ativa e verificada?
Verifique o extrato de transações

Verificações:

O QR Code está válido? (não expirou)
O valor está correto?
A chave PIX está correta?
Verifique o status do depósito na API
Confira os webhooks de confirmação

Verificações:

A soma dos percentuais é 100%?
As contas existem e estão ativas?
As contas têm perfil gateway configurado?
Use o endpoint de validação de splits

3. Boas Práticas

Use HTTPS sempre: Nunca envie tokens ou dados sensíveis em HTTP
Implemente retry logic: Webhooks podem falhar, implemente retentativas
Valide antes de criar: Use endpoints de validação antes de criar transações
Monitore rate limits: Respeite os limites de requisições
Log tudo: Mantenha logs de todas as requisições e respostas
Teste em sandbox: Use o ambiente de testes antes de produção

4. Precisão de Valores

A API usa strings para valores monetários para evitar problemas de precisão:

// ✅ Correto
{
  "amount": "100.50"
}

//  Incorreto (pode perder precisão)
{
  "amount": 100.50
}

5. Precisa de Ajuda?

Suporte Técnico

Abra um chamado no painel

Email

suporte@ajnapay.com.br

Chat ao Vivo

Seg-Sex, 9h-18h

Anterior: Splits Voltar para Guides