Códigos de Erro

Visão Geral

A API EconPay usa códigos de status HTTP padrão para indicar sucesso ou falha de uma requisição.

Códigos de Status HTTP

Código	Significado	Descrição
200	OK	Requisição bem-sucedida
400	Bad Request	Dados inválidos ou faltando
401	Unauthorized	Token JWT inválido ou expirado
403	Forbidden	Sem permissão para acessar o recurso
404	Not Found	Recurso não encontrado
500	Internal Server Error	Erro interno do servidor

Estrutura de Erro

Quando ocorre um erro, a API retorna um JSON com detalhes:

{
  "success": false,
  "message": "Descrição do erro",
  "error": "Detalhes técnicos do erro"
}

Erros Comuns

Autenticação

401 - Token JWT inválido ou expirado

Causa: O token JWT não é válido ou expirou (1 hora de validade)Solução:

// Faça login novamente para obter um novo token
const response = await fetch('https://api.econpay.com.br/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'sua-senha'
  })
});

403 - Access token inválido

Causa: O access_token fornecido não existe ou está incorretoSolução:

Verifique o access_token no dashboard
Certifique-se de usar o token correto (produção vs sandbox)
Regenere o token se necessário

403 - Permissões insuficientes

Causa: O usuário não tem permissão para executar a açãoSolução:

Verifique as permissões do usuário no dashboard
Entre em contato com o administrador da conta

Pagamentos

400 - Dados de pagamento inválidos

Causa: Campos obrigatórios faltando ou formato incorretoExemplo de erro:

{
  "success": false,
  "message": "Dados de pagamento inválidos",
  "error": "Campo 'customer.email' é obrigatório"
}

Solução:

Verifique todos os campos obrigatórios
Valide formatos (email, CPF, telefone)
Consulte a documentação do endpoint

400 - Cartão é obrigatório para pagamentos de crédito/débito

Causa: Tentou criar pagamento com cartão sem enviar dados do cartãoSolução:

{
  "payment": {
    "type": "credit",
    "installments": 3,
    "credit_card": {
      "number": "4000000000000010",
      "holder_name": "NOME NO CARTAO",
      "exp_month": 12,
      "exp_year": 2025,
      "cvv": "123"
    }
  }
}

400 - Valor mínimo não atingido

Causa: O valor da transação é menor que R$ 5,00Exemplo de erro:

{
  "success": false,
  "message": "Valor mínimo não atingido",
  "error": "O valor mínimo para transações é R$ 5,00. Valor enviado: R$ 2,00"
}

Solução:

Certifique-se de que o valor total é >= 500 centavos (R$ 5,00)

400 - Formato de data de expiração inválido

Causa: Data de expiração do cartão em formato incorretoSolução:

{
  "credit_card": {
    "exp_month": 12,    // Número de 1 a 12
    "exp_year": 2025    // Ano completo (YYYY)
  }
}

Transações

404 - Transação não encontrada

Causa: O ID da transação não existe ou não pertence à sua contaSolução:

Verifique se o ID está correto
Certifique-se de que a transação pertence à sua conta
Use o endpoint de listagem para encontrar transações

400 - Transação não pode ser estornada

Causa: A transação não está em um status que permite estornoExemplo de erro:

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Apenas transações com status APPROVED podem ser estornadas. Status atual: PENDING"
}

Solução:

Verifique o status da transação
Aguarde a aprovação antes de tentar estornar
Transações PENDING, FAILED ou REFUNDED não podem ser estornadas

Configuração

404 - Configuração de roteamento não encontrada

Causa: Não há configuração de subadquirente para o tipo de pagamentoExemplo de erro:

{
  "success": false,
  "message": "Configuração de roteamento não encontrada",
  "error": "Nenhuma configuração encontrada para company_id: 1 e payment_type: pix"
}

Solução:

Configure a subadquirente no dashboard
Entre em contato com o suporte
Verifique se o método de pagamento está habilitado

Erros de Subadquirente

Quando a subadquirente (Firebank, etc) retorna erro:

{
  "success": false,
  "message": "Erro ao processar pagamento na subadquirente",
  "error": "Cartão recusado pela operadora"
}

Erros Comuns de Cartão

Erro	Causa	Solução
Cartão recusado	Sem limite ou bloqueado	Cliente deve contatar banco
Cartão expirado	Data de validade passou	Usar cartão válido
CVV inválido	CVV incorreto	Verificar código de segurança
Dados inválidos	Número ou nome incorreto	Verificar dados do cartão

Tratamento de Erros

Exemplo em JavaScript

async function createPayment(paymentData) {
  try {
    const response = await fetch('https://api.econpay.com.br/payments/order', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(paymentData)
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      // Tratar erro baseado no status
      switch (response.status) {
        case 400:
          console.error('Dados inválidos:', data.error);
          break;
        case 401:
          console.error('Token expirado, fazendo login novamente...');
          await refreshToken();
          break;
        case 403:
          console.error('Sem permissão:', data.error);
          break;
        case 404:
          console.error('Recurso não encontrado:', data.error);
          break;
        case 500:
          console.error('Erro no servidor:', data.error);
          break;
        default:
          console.error('Erro desconhecido:', data.error);
      }
      
      throw new Error(data.message);
    }
    
    return data;
  } catch (error) {
    console.error('Erro ao criar pagamento:', error);
    throw error;
  }
}

Exemplo em Python

import requests

def create_payment(payment_data, token):
    try:
        response = requests.post(
            'https://api.econpay.com.br/payments/order',
            headers={
                'Authorization': f'Bearer {token}',
                'Content-Type': 'application/json'
            },
            json=payment_data
        )
        
        data = response.json()
        
        if not response.ok:
            # Tratar erro baseado no status
            if response.status_code == 400:
                print(f'Dados inválidos: {data["error"]}')
            elif response.status_code == 401:
                print('Token expirado, fazendo login novamente...')
                refresh_token()
            elif response.status_code == 403:
                print(f'Sem permissão: {data["error"]}')
            elif response.status_code == 404:
                print(f'Recurso não encontrado: {data["error"]}')
            elif response.status_code == 500:
                print(f'Erro no servidor: {data["error"]}')
            
            raise Exception(data['message'])
        
        return data
    except requests.exceptions.RequestException as e:
        print(f'Erro ao criar pagamento: {e}')
        raise

Retry Logic

Para erros temporários (500, timeout), implemente retry com backoff exponencial:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Apenas retry em erros 500 ou timeout
      if (error.status !== 500 && error.code !== 'ETIMEDOUT') {
        throw error;
      }
      
      // Backoff exponencial: 1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Uso
const payment = await retryRequest(() => createPayment(paymentData));

Suporte

Se você encontrar um erro não documentado ou precisar de ajuda:

Contate o Suporte

Nossa equipe está pronta para ajudar

Início

Guias

Visão Geral

Códigos de Status HTTP

Estrutura de Erro

Erros Comuns

Autenticação

Pagamentos

Transações

Configuração

Erros de Subadquirente

Erros Comuns de Cartão

Tratamento de Erros

Exemplo em JavaScript

Exemplo em Python

Retry Logic

Suporte

Contate o Suporte

​Visão Geral

​Códigos de Status HTTP

​Estrutura de Erro

​Erros Comuns

​Autenticação

​Pagamentos

​Transações

​Configuração

​Erros de Subadquirente

​Erros Comuns de Cartão

​Tratamento de Erros

​Exemplo em JavaScript

​Exemplo em Python

​Retry Logic

​Suporte

Contate o Suporte

Visão Geral

Códigos de Status HTTP

Estrutura de Erro

Erros Comuns

Autenticação

Pagamentos

Transações

Configuração

Erros de Subadquirente

Erros Comuns de Cartão

Tratamento de Erros

Exemplo em JavaScript

Exemplo em Python

Retry Logic

Suporte