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
2xx - Sucesso
2xx - Sucesso
4xx - Erro do Cliente
4xx - Erro do Cliente
A requisição contém parâmetros inválidos ou está mal formatada
Autenticação necessária ou credenciais inválidas
Não há permissão para acessar o recurso
O recurso solicitado não foi encontrado
Conflito ao tentar processar a requisição
Os dados enviados são válidos, mas não podem ser processados
Limite de requisições excedido
Códigos de Erro Específicos
Autenticação e Autorização
As credenciais (Client ID e/ou Client Secret) são inválidasSoluçã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 informadasSolução: Certifique-se de incluir os cabeçalhos
ci e cs em todas as requisiçõesO IP que está tentando realizar a operação não está autorizadoSolução: Cadastre o IP do servidor no Dashboard RelaxPay em GATEWAY/CHECKOUT > GERENCIAMENTO DE IPs
A conta ainda não teve seus documentos validadosSolução: Complete o processo de validação de documentos no Dashboard RelaxPay
PIX Cash-in
O valor informado é inválidoSolução: Certifique-se de enviar um valor positivo e válido (mínimo de R$ 1,00)
Um campo obrigatório não foi informadoSolução: Verifique se todos os campos obrigatórios foram incluídos na requisição
A URL de callback informada é inválidaSolução: Certifique-se de informar uma URL válida, acessível publicamente e iniciada com https://
A data de vencimento informada é inválidaSolução: Informe uma data de vencimento futura no formato AAAA-MM-DD
PIX Cash-out
Saldo insuficiente para realizar a transferênciaSolução: Adicione fundos à sua conta ou reduza o valor da transferência
A chave PIX informada não foi encontradaSolução: Verifique se a chave PIX e o tipo de chave estão corretos
A chave PIX não pertence ao documento informadoSolução: Confirme se o documento informado corresponde ao titular da chave PIX
O externalId já foi utilizado em outra transaçãoSolução: Utilize um identificador único para cada transação
O tipo de chave PIX informado é inválidoSolução: Utilize um dos tipos válidos: document, phoneNumber, email, randomKey, paymentCode
Webhooks
A verificação da assinatura do webhook falhouSolução: Certifique-se de estar validando corretamente a assinatura com seu Client Secret
A URL de webhook informada não está acessívelSolução: Verifique se o endpoint está disponível e respondendo corretamente
Limites e Restrições
O limite diário de operações foi excedidoSoluçã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 permitidoSolução: Reduza o valor da transação ou solicite um aumento de limite
O limite de requisições por minuto foi excedidoSolução: Implemente uma lógica de retry com exponential backoff
Como Tratar Erros
1
Validação Prévia
Implemente validações no lado do cliente antes de enviar requisições
2
Tratamento Estruturado
Use estruturas try/catch para capturar e tratar erros
3
Função de Tratamento
Implemente uma função específica para tratar os erros da API
4
Retentativas Inteligentes
Implemente uma estratégia de retentativa para erros temporários
Exceções Comuns e Soluções
Erro de validação de assinatura de webhook
Erro de validação de assinatura de webhook
Verifique se está utilizando o algoritmo HMAC-SHA256 correto
Confirme se o Client Secret utilizado é o mesmo associado ao Client ID
Verifique se está comparando as assinaturas de forma segura (utilizando comparação de tempo constante)
Certifique-se de que o corpo do webhook não está sendo modificado antes da validação
Erro de IP não autorizado
Erro de IP não autorizado
Verifique se o IP do seu servidor está cadastrado no Dashboard
Lembre-se que, se seu servidor estiver atrás de um proxy, o IP visto pela RelaxPay será o do proxy
Utilize um IP fixo para suas operações de PIX Cash-out
Ao trabalhar com múltiplos servidores, cadastre todos os IPs envolvidos
Erros de limites excedidos
Erros de limites excedidos
Verifique o limite diário da sua conta no Dashboard
Para operações de alto valor, solicite um aumento de limite
Monitore o uso dos seus limites diários para evitar surpresas
Implemente lógica de fila para distribuir operações ao longo do dia