> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de Erro

> Entenda os códigos de erro da API e como resolvê-los

## 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:

```json theme={null}
{
  "success": false,
  "message": "Descrição do erro",
  "error": "Detalhes técnicos do erro"
}
```

## Erros Comuns

### Autenticação

<AccordionGroup>
  <Accordion title="401 - Token JWT inválido ou expirado">
    **Causa:** O token JWT não é válido ou expirou (1 hora de validade)

    **Solução:**

    ```javascript theme={null}
    // 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: 'seu-email@exemplo.com',
        password: 'sua-senha'
      })
    });
    ```
  </Accordion>

  <Accordion title="403 - Access token inválido">
    **Causa:** O `access_token` fornecido não existe ou está incorreto

    **Solução:**

    * Verifique o access\_token no dashboard
    * Certifique-se de usar o token correto (produção vs sandbox)
    * Regenere o token se necessário
  </Accordion>

  <Accordion title="403 - Permissões insuficientes">
    **Causa:** O usuário não tem permissão para executar a ação

    **Solução:**

    * Verifique as permissões do usuário no dashboard
    * Entre em contato com o administrador da conta
  </Accordion>
</AccordionGroup>

### Pagamentos

<AccordionGroup>
  <Accordion title="400 - Dados de pagamento inválidos">
    **Causa:** Campos obrigatórios faltando ou formato incorreto

    **Exemplo de erro:**

    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="400 - Cartão é obrigatório para pagamentos de crédito/débito">
    **Causa:** Tentou criar pagamento com cartão sem enviar dados do cartão

    **Solução:**

    ```json theme={null}
    {
      "payment": {
        "type": "credit",
        "installments": 3,
        "credit_card": {
          "number": "4000000000000010",
          "holder_name": "NOME NO CARTAO",
          "exp_month": 12,
          "exp_year": 2025,
          "cvv": "123"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="400 - Valor mínimo não atingido">
    **Causa:** O valor da transação é menor que R\$ 5,00

    **Exemplo de erro:**

    ```json theme={null}
    {
      "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)
  </Accordion>

  <Accordion title="400 - Formato de data de expiração inválido">
    **Causa:** Data de expiração do cartão em formato incorreto

    **Solução:**

    ```json theme={null}
    {
      "credit_card": {
        "exp_month": 12,    // Número de 1 a 12
        "exp_year": 2025    // Ano completo (YYYY)
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Transações

<AccordionGroup>
  <Accordion title="404 - Transação não encontrada">
    **Causa:** O ID da transação não existe ou não pertence à sua conta

    **Soluçã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
  </Accordion>

  <Accordion title="400 - Transação não pode ser estornada">
    **Causa:** A transação não está em um status que permite estorno

    **Exemplo de erro:**

    ```json theme={null}
    {
      "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
  </Accordion>
</AccordionGroup>

### Configuração

<AccordionGroup>
  <Accordion title="404 - Configuração de roteamento não encontrada">
    **Causa:** Não há configuração de subadquirente para o tipo de pagamento

    **Exemplo de erro:**

    ```json theme={null}
    {
      "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
  </Accordion>
</AccordionGroup>

## Erros de Subadquirente

Quando a subadquirente (Firebank, etc) retorna erro:

```json theme={null}
{
  "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

```javascript theme={null}
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

```python theme={null}
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:

```javascript theme={null}
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:

<Card title="Contate o Suporte" icon="headset" href="mailto:suporte@econpay.com.br">
  Nossa equipe está pronta para ajudar
</Card>