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

# Errors

> Understanding API error responses

## Error Response Format

All errors follow a consistent format:

```json theme={null}
{
  "error": "error message",
  "error_code": "ERROR_CODE"
}
```

## HTTP Status Codes

* **200 OK**: Successful request;
* **400 Bad Request**: Invalid request parameters;
* **401 Unauthorized**: API key missing or invalid;
* **403 Forbidden**: API key does not have necessary permissions or IP not allowed;
* **406 Not Acceptable**: Request cannot be processed (e.g., market closed);
* **429 Too Many Requests**: Rate limit exceeded;
* **500 Internal Server Error**: Server error.

## Error Codes

### Order Placement Errors

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

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

**Description**: Price is invalid (must be between 0-100 ticks for limit orders, or value\_cents must be positive for market orders)

***

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

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

**Description**: Quantity is invalid (must be positive)

***

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

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

**Description**: Account does not have sufficient balance to place the order

***

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

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

**Description**: Account does not have sufficient contracts to sell

***

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

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

**Description**: Market does not have sufficient liquidity to execute the order

***

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

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

**Description**: Order not found (when trying to cancel)

***

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

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

**Description**: User is not authorized to perform this action

***

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

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

**Description**: Market is closed and no longer accepting orders

***

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

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

**Description**: An unexpected error occurred

## Authentication Errors

### 401 Unauthorized

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

**Causes**:

* Missing `X-Api-Key` header
* Invalid API key
* API key expired
* API key is disabled

**Solution**: Verify that your API key is correct and active in [Profile → Security](https://staging.voxfi.com.br/profile)

### 403 Forbidden

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

**Causes**:

* Your IP address is not on the API key whitelist

**Solution**: Add your IP address to the API key's allowed IPs list

## Rate Limiting

### 429 Too Many Requests

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

**Description**: You have exceeded the rate limit for this endpoint

**Response Headers**:

* `Retry-After`: Number of seconds to wait before trying again

**Solution**: Wait for the specified time before making another request

## Error Handling Best Practices

1. **Check Status Codes**: Always check HTTP status codes before processing responses
2. **Handle Rate Limits**: Implement exponential backoff for rate limit errors
3. **Validate Input**: Validate all parameters before sending requests
4. **Check Market Status**: Verify that the market is open before placing orders
5. **Monitor Balance**: Check available balance before placing orders
6. **Log Errors**: Log error codes and messages for debugging

## Error Handling Example

<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(`Rate limited. Try again after ${retryAfter} seconds`);
        // Implement retry logic
      } else if (data.error_code) {
        console.error(`Error ${data.error_code}: ${data.error}`);
        // Handle specific error codes
      } else {
        console.error(`Error: ${data.error}`);
      }
      return;
    }

    // Process successful response
    console.log('Order placed:', data);
  } catch (error) {
    console.error('Network error:', 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"Rate limited. Try again after {retry_after} seconds")
                  time.sleep(retry_after)
                  return place_order(api_key, order_data)  # Try again
              elif 'error_code' in data:
                  print(f"Error {data['error_code']}: {data['error']}")
              else:
                  print(f"Error: {data.get('error', 'Unknown error')}")
              return None
          
          return data
      except requests.exceptions.RequestException as e:
          print(f"Network error: {e}")
          return None
  ```
</CodeGroup>