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

# Erros

> Entendendo respostas de erro da API

## Formato de Resposta de Erro

Todos os erros seguem um formato consistente:

```json theme={null}
{
  "error": "mensagem de erro",
  "error_code": "CODIGO_ERRO"
}
```

## Códigos de Status HTTP

* **200 OK**: Requisição bem-sucedida;
* **400 Bad Request**: Parâmetros de requisição inválidos;
* **401 Unauthorized**: Chave de API ausente ou inválida;
* **403 Forbidden**: Chave de API não tem permissões necessárias ou IP não permitido;
* **406 Not Acceptable**: Requisição não pode ser processada (ex: mercado fechado);
* **429 Too Many Requests**: Limite de taxa excedido;
* **500 Internal Server Error**: Erro do servidor.

## Códigos de Erro

### Erros de Colocação de Ordem

<ResponseField name="PO1" status="406">
  <ResponseFieldObject name="error" type="string">
    "INVALID\_PRICE"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO1"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Preço é inválido (deve estar entre 0-100 ticks para ordens limitadas, ou value\_cents deve ser positivo para ordens a mercado)

***

<ResponseField name="PO2" status="406">
  <ResponseFieldObject name="error" type="string">
    "INVALID\_QUANTITY"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO2"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Quantidade é inválida (deve ser positiva)

***

<ResponseField name="PO3" status="406">
  <ResponseFieldObject name="error" type="string">
    "INSUFFICIENT\_FUNDS"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO3"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Conta não tem saldo suficiente para fazer a ordem

***

<ResponseField name="PO4" status="406">
  <ResponseFieldObject name="error" type="string">
    "INSUFFICIENT\_ASSETS"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO4"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Conta não tem contratos suficientes para vender

***

<ResponseField name="PO5" status="406">
  <ResponseFieldObject name="error" type="string">
    "INSUFFICIENT\_LIQUIDITY"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO5"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Mercado não tem liquidez suficiente para executar a ordem

***

<ResponseField name="PO6" status="406">
  <ResponseFieldObject name="error" type="string">
    "ORDER\_NOT\_FOUND"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO6"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Ordem não encontrada (ao tentar cancelar)

***

<ResponseField name="PO7" status="403">
  <ResponseFieldObject name="error" type="string">
    "UNAUTHORIZED"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO7"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Usuário não está autorizado a realizar esta ação

***

<ResponseField name="PO8" status="406">
  <ResponseFieldObject name="error" type="string">
    "MARKET\_CLOSED"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "PO8"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Mercado está fechado e não está mais aceitando ordens

***

<ResponseField name="-1" status="500">
  <ResponseFieldObject name="error" type="string">
    "UNKNOWN\_ERROR"
  </ResponseFieldObject>

  <ResponseFieldObject name="error_code" type="string">
    "-1"
  </ResponseFieldObject>
</ResponseField>

**Descrição**: Ocorreu um erro inesperado

## Erros de Autenticação

### 401 Unauthorized

```json theme={null}
{
  "error": "unauthorized"
}
```

**Causas**:

* Cabeçalho `X-Api-Key` ausente
* Chave de API inválida
* Chave de API expirou
* Chave de API está desabilitada

**Solução**: Verifique se sua chave de API está correta e ativa em [Perfil → Segurança](https://staging.voxfi.com.br/profile)

### 403 Forbidden

```json theme={null}
{
  "error": "ip not allowed"
}
```

**Causas**:

* Seu endereço IP não está na whitelist da chave de API

**Solução**: Adicione seu endereço IP à lista de IPs permitidos da chave de API

## Limitação de Taxa

### 429 Too Many Requests

```json theme={null}
{
  "error": "rate limit exceeded",
  "retry_after": 60
}
```

**Descrição**: Você excedeu o limite de taxa para este endpoint

**Cabeçalhos de Resposta**:

* `Retry-After`: Número de segundos para esperar antes de tentar novamente

**Solução**: Aguarde o tempo especificado antes de fazer outra requisição

## Boas Práticas de Tratamento de Erros

1. **Verificar Códigos de Status**: Sempre verifique códigos de status HTTP antes de processar respostas
2. **Tratar Limites de Taxa**: Implemente backoff exponencial para erros de limite de taxa
3. **Validar Entrada**: Valide todos os parâmetros antes de enviar requisições
4. **Verificar Status do Mercado**: Verifique se o mercado está aberto antes de fazer ordens
5. **Monitorar Saldo**: Verifique o saldo disponível antes de fazer ordens
6. **Registrar Erros**: Registre códigos e mensagens de erro para depuração

## Exemplo de Tratamento de Erros

<CodeGroup>
  ```javascript JavaScript theme={null}
  try {
    const response = await fetch('https://data-api-dev.voxfi.com.br/v1/trade/order', {
      method: 'POST',
      headers: {
        'X-Api-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(orderData)
    });

    const data = await response.json();

    if (!response.ok) {
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        console.error(`Limitado por taxa. Tente novamente após ${retryAfter} segundos`);
        // Implementar lógica de retry
      } else if (data.error_code) {
        console.error(`Erro ${data.error_code}: ${data.error}`);
        // Tratar códigos de erro específicos
      } else {
        console.error(`Erro: ${data.error}`);
      }
      return;
    }

    // Processar resposta bem-sucedida
    console.log('Ordem feita:', data);
  } catch (error) {
    console.error('Erro de rede:', error);
  }
  ```

  ```python Python theme={null}
  import requests
  import time

  def place_order(api_key, order_data):
      try:
          response = requests.post(
              'https://data-api-dev.voxfi.com.br/v1/trade/order',
              headers={
                  'X-Api-Key': api_key,
                  'Content-Type': 'application/json'
              },
              json=order_data
          )
          
          data = response.json()
          
          if not response.ok:
              if response.status_code == 429:
                  retry_after = int(response.headers.get('Retry-After', 60))
                  print(f"Limitado por taxa. Tente novamente após {retry_after} segundos")
                  time.sleep(retry_after)
                  return place_order(api_key, order_data)  # Tentar novamente
              elif 'error_code' in data:
                  print(f"Erro {data['error_code']}: {data['error']}")
              else:
                  print(f"Erro: {data.get('error', 'Erro desconhecido')}")
              return None
          
          return data
      except requests.exceptions.RequestException as e:
          print(f"Erro de rede: {e}")
          return None
  ```
</CodeGroup>