Skip to main content
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

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "PIX_KEY_NOT_FOUND",
  "details": "A chave PIX informada não foi encontrada"
}

Códigos de Status HTTP

200 - OK
success
A requisição foi processada com sucesso
201 - Created
success
Um novo recurso foi criado com sucesso
204 - No Content
success
A requisição foi processada, mas não há conteúdo para retornar
400 - Bad Request
error
A requisição contém parâmetros inválidos ou está mal formatada
401 - Unauthorized
error
Autenticação necessária ou credenciais inválidas
403 - Forbidden
error
Não há permissão para acessar o recurso
404 - Not Found
error
O recurso solicitado não foi encontrado
409 - Conflict
error
Conflito ao tentar processar a requisição
422 - Unprocessable Entity
error
Os dados enviados são válidos, mas não podem ser processados
429 - Too Many Requests
warning
Limite de requisições excedido
500 - Internal Server Error
error
Erro interno no servidor
502 - Bad Gateway
error
Erro de comunicação entre servidores
503 - Service Unavailable
error
Serviço temporariamente indisponível
504 - Gateway Timeout
error
Tempo limite de resposta excedido

Códigos de Erro Específicos

Autenticação e Autorização

INVALID_CREDENTIALS
error
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
MISSING_CREDENTIALS
error
As credenciais não foram informadasSolução: Certifique-se de incluir os cabeçalhos ci e cs em todas as requisições
UNAUTHORIZED_IP
error
O 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
ACCOUNT_DOCUMENTS_NOT_VALIDATED
error
A conta ainda não teve seus documentos validadosSolução: Complete o processo de validação de documentos no Dashboard RelaxPay

PIX Cash-in

INVALID_AMOUNT
error
O valor informado é inválidoSolução: Certifique-se de enviar um valor positivo e válido (mínimo de R$ 1,00)
MISSING_REQUIRED_FIELD
error
Um campo obrigatório não foi informadoSolução: Verifique se todos os campos obrigatórios foram incluídos na requisição
INVALID_CALLBACK_URL
error
A URL de callback informada é inválidaSolução: Certifique-se de informar uma URL válida, acessível publicamente e iniciada com https://
INVALID_DUE_DATE
error
A data de vencimento informada é inválidaSolução: Informe uma data de vencimento futura no formato AAAA-MM-DD

PIX Cash-out

NO_FUNDS
error
Saldo insuficiente para realizar a transferênciaSolução: Adicione fundos à sua conta ou reduza o valor da transferência
PIX_KEY_NOT_FOUND
error
A chave PIX informada não foi encontradaSolução: Verifique se a chave PIX e o tipo de chave estão corretos
DOCUMENT_VALIDATE
error
A chave PIX não pertence ao documento informadoSolução: Confirme se o documento informado corresponde ao titular da chave PIX
DUPLICATE_EXTERNAL_ID
warning
O externalId já foi utilizado em outra transaçãoSolução: Utilize um identificador único para cada transação
INVALID_KEY_TYPE
error
O tipo de chave PIX informado é inválidoSolução: Utilize um dos tipos válidos: document, phoneNumber, email, randomKey, paymentCode

Webhooks

WEBHOOK_VERIFICATION_FAILED
error
A verificação da assinatura do webhook falhouSolução: Certifique-se de estar validando corretamente a assinatura com seu Client Secret
WEBHOOK_URL_UNREACHABLE
error
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

DAILY_LIMIT_EXCEEDED
error
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
TRANSACTION_LIMIT_EXCEEDED
error
O valor da transação excede o limite permitidoSolução: Reduza o valor da transação ou solicite um aumento de limite
RATE_LIMIT_EXCEEDED
warning
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
try {
  const response = await fetch('https://ws.relaxpay.site/api/v1/gateway/pix-payment', {
    method: 'POST',
    headers: {
      'ci': process.env.RELAXPAY_CLIENT_ID,
      'cs': process.env.RELAXPAY_CLIENT_SECRET,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      // Dados da requisição
    })
  });
  
  const data = await response.json();
  
  if (!response.ok) {
    // Tratar erros específicos
    handleApiError(data);
    return;
  }
  
  // Processar resposta de sucesso
  processSuccess(data);
} catch (error) {
  // Tratar erros de rede ou outros erros inesperados
  handleNetworkError(error);
}
3

Função de Tratamento

Implemente uma função específica para tratar os erros da API
function handleApiError(error) {
  const errorCode = error.message;
  
  switch (errorCode) {
    case 'NO_FUNDS':
      console.error('Saldo insuficiente para realizar a operação');
      notifyUser('Saldo insuficiente para realizar a operação');
      break;
    case 'PIX_KEY_NOT_FOUND':
      console.error('Chave PIX não encontrada');
      notifyUser('A chave PIX informada não foi encontrada. Verifique e tente novamente.');
      break;
    // Outros casos específicos
    default:
      console.error(`Erro desconhecido: ${errorCode}`);
      notifyUser('Ocorreu um erro ao processar sua solicitação. Tente novamente mais tarde.');
  }
}
4

Retentativas Inteligentes

Implemente uma estratégia de retentativa para erros temporários
async function requestWithRetry(url, options, maxRetries = 3) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429 || (response.status >= 500 && response.status < 600)) {
        // Calcular tempo de espera com exponential backoff
        const waitTime = Math.min(Math.pow(2, retries) * 1000, 10000);
        retries++;
        
        if (retries < maxRetries) {
          console.log(`Aguardando ${waitTime}ms antes da tentativa ${retries + 1}/${maxRetries}`);
          await new Promise(resolve => setTimeout(resolve, waitTime));
          continue;
        }
      }
      
      return response;
    } catch (error) {
      retries++;
      
      if (retries >= maxRetries) {
        throw error;
      }
      
      // Aguardar antes de tentar novamente
      await new Promise(resolve => setTimeout(resolve, 1000 * retries));
    }
  }
}

Exceções Comuns e Soluções

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
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
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
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 [email protected].