Códigos de Erro
Lista completa de códigos de erro da API RelaxPay e como solucioná-los
Esta página contém todos os códigos de erro que podem ser retornados pela API RelaxPay, com descrições detalhadas e instruções para correção.
Visão Geral
A API RelaxPay utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição. Além disso, retornamos códigos de erro específicos que fornecem mais detalhes sobre o problema encontrado.
Estrutura de erros
Todas as respostas de erro seguem uma estrutura padronizada para facilitar o tratamento
Mensagens descritivas
Cada código de erro inclui uma mensagem detalhada sobre o problema
Formato de Resposta de Erro
Códigos de Status HTTP
Códigos de Erro Específicos
Autenticação e Autorização
As credenciais (Client ID e/ou Client Secret) são inválidas
Solução: Verifique se os valores de CI e CS estão corretos e se foram enviados nos cabeçalhos apropriados
As credenciais não foram informadas
Solução: Certifique-se de incluir os cabeçalhos ci
e cs
em todas as requisições
O IP que está tentando realizar a operação não está autorizado
Solução: Cadastre o IP do servidor no Dashboard RelaxPay em GATEWAY/CHECKOUT > GERENCIAMENTO DE IPs
A conta ainda não teve seus documentos validados
Solução: Complete o processo de validação de documentos no Dashboard RelaxPay
PIX Cash-in
O valor informado é inválido
Solução: Certifique-se de enviar um valor positivo e válido (mínimo de R$ 1,00)
Um campo obrigatório não foi informado
Solução: Verifique se todos os campos obrigatórios foram incluídos na requisição
A URL de callback informada é inválida
Solução: Certifique-se de informar uma URL válida, acessível publicamente e iniciada com https://
A data de vencimento informada é inválida
Solução: Informe uma data de vencimento futura no formato AAAA-MM-DD
PIX Cash-out
Saldo insuficiente para realizar a transferência
Solução: Adicione fundos à sua conta ou reduza o valor da transferência
A chave PIX informada não foi encontrada
Solução: Verifique se a chave PIX e o tipo de chave estão corretos
A chave PIX não pertence ao documento informado
Solução: Confirme se o documento informado corresponde ao titular da chave PIX
O externalId já foi utilizado em outra transação
Solução: Utilize um identificador único para cada transação
O tipo de chave PIX informado é inválido
Solução: Utilize um dos tipos válidos: document, phoneNumber, email, randomKey, paymentCode
Webhooks
A verificação da assinatura do webhook falhou
Solução: Certifique-se de estar validando corretamente a assinatura com seu Client Secret
A URL de webhook informada não está acessível
Solução: Verifique se o endpoint está disponível e respondendo corretamente
Limites e Restrições
O limite diário de operações foi excedido
Solução: Aguarde o próximo dia útil ou solicite um aumento de limite através do Dashboard
O valor da transação excede o limite permitido
Solução: Reduza o valor da transação ou solicite um aumento de limite
O limite de requisições por minuto foi excedido
Solução: Implemente uma lógica de retry com exponential backoff
Como Tratar Erros
Validação Prévia
Implemente validações no lado do cliente antes de enviar requisições
Tratamento Estruturado
Use estruturas try/catch para capturar e tratar erros
Função de Tratamento
Implemente uma função específica para tratar os erros da API
Retentativas Inteligentes
Implemente uma estratégia de retentativa para erros temporários
Exceções Comuns e Soluções
Se você estiver enfrentando um erro que não está documentado aqui ou precisar de ajuda adicional, entre em contato com nosso suporte técnico em suporte@relaxpay.app.