Skip to main content

​
Error Response Format

All errors follow a consistent format: 
{
  "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

​
PO1
Description: Price is invalid (must be between 0-100 ticks for limit orders, or value_cents must be positive for market orders)
​
PO2
Description: Quantity is invalid (must be positive)
​
PO3
Description: Account does not have sufficient balance to place the order
​
PO4
Description: Account does not have sufficient contracts to sell
​
PO5
Description: Market does not have sufficient liquidity to execute the order
​
PO6
Description: Order not found (when trying to cancel)
​
PO7
Description: User is not authorized to perform this action
​
PO8
Description: Market is closed and no longer accepting orders
​
-1
Description: An unexpected error occurred

​
Authentication Errors

​
401 Unauthorized

{
  "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

​
403 Forbidden

{
  "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

{
  "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

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);
}