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

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álidas

Soluçã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 informadas

Soluçã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á autorizado

Soluçã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 validados

Solução: Complete o processo de validação de documentos no Dashboard RelaxPay

PIX Cash-in

INVALID_AMOUNT
error

O valor informado é inválido

Soluçã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 informado

Solução: Verifique se todos os campos obrigatórios foram incluídos na requisição

INVALID_CALLBACK_URL
error

A URL de callback informada é inválida

Soluçã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álida

Solução: Informe uma data de vencimento futura no formato AAAA-MM-DD

PIX Cash-out

NO_FUNDS
error

Saldo insuficiente para realizar a transferência

Solução: Adicione fundos à sua conta ou reduza o valor da transferência

PIX_KEY_NOT_FOUND
error

A chave PIX informada não foi encontrada

Soluçã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 informado

Solução: Confirme se o documento informado corresponde ao titular da chave PIX

DUPLICATE_EXTERNAL_ID
warning

O externalId já foi utilizado em outra transação

Solução: Utilize um identificador único para cada transação

INVALID_KEY_TYPE
error

O tipo de chave PIX informado é inválido

Solução: Utilize um dos tipos válidos: document, phoneNumber, email, randomKey, paymentCode

Webhooks

WEBHOOK_VERIFICATION_FAILED
error

A verificação da assinatura do webhook falhou

Soluçã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ível

Soluçã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 excedido

Soluçã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 permitido

Soluçã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 excedido

Soluçã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

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.