Errors

​

Error Codes

​

VoxFi Custom Codes

​

4001 - Unauthorized

• Verify that you are providing the auth field in the subscribe message;
• Confirm that the API key is correct and active;
• Check if the API key has expired or been disabled;
• Verify that your IP is on the API key’s whitelist.

​

4002 - Invalid Params

• "session is required": Invalid or missing session

​

4003 - Server Error

​

4004 - Invalid Message

• Invalid channel field (must be "user", "market" or "event");
• Invalid filter field (must be "all", "orderbook", "trades" or empty);
• Missing required fields (markets for market channel, events for event channel, auth for user channel);
• Invalid JSON format;
• Invalid message type (must be "subscribe" or "unsubscribe").

• "invalid channel": Specified channel does not exist;
• "invalid filter": Specified filter is invalid;
• "invalid message type": Invalid message type.

​

Standard WebSocket Codes

• 1000: Normal closure (not an error);
• 1001: Endpoint going away;
• 1002: Protocol error;
• 1006: Connection closed abnormally (without close code);
• 1011: Internal server error.

​

Error Handling

const ws = new WebSocket('wss://data-ws.voxfi.com.br');

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = (event) => {
  console.log('Connection closed:', event.code, event.reason);
  
  // Handle different error codes
  switch (event.code) {
    case 4001:
      console.error('Unauthorized. Check your API key.');
      break;
    case 4002:
      console.error('Invalid parameters. Check the connection.');
      break;
    case 4003:
      console.error('Server error. Try again later.');
      break;
    case 4004:
      console.error('Invalid message. Check the message format.');
      break;
    case 1002:
      console.error('Protocol error. Check the URL and message format.');
      break;
    case 1006:
      console.error('Connection closed abnormally. Possible network issue.');
      break;
    default:
      console.error('Unknown error:', event.code, event.reason);
  }
  
  // Implement reconnection if necessary
  if (event.code !== 1000) { // 1000 = normal closure
    setTimeout(() => {
      console.log('Attempting to reconnect...');
      connect(); // Your connection function
    }, 5000);
  }
};

​

Error Messages

​

Common Error Messages

• "session is required" (code 4002): Invalid or missing session during initial validation;
• "invalid channel" (code 4004): Specified channel does not exist (must be "user", "market" or "event");
• "invalid filter" (code 4004): Specified filter is invalid (must be "all", "orderbook", "trades" or empty);
• "invalid message type" (code 4004): Invalid message type (must be "subscribe" or "unsubscribe");
• "failed to check x-api-key" (code 4001): Failed to validate API key;
• Go JSON error messages when there is a failure to unmarshal the message (code 4004).

​

Error Handling Best Practices

1. Always Handle onclose: Implement handling for the onclose event to detect disconnections;
2. Check Error Codes: Use error codes to determine the cause and take appropriate actions;
3. Smart Reconnection: Implement automatic reconnection with exponential backoff for temporary errors;
4. Don’t Reconnect for Permanent Errors: Errors like 1003 (unauthorized) or 1008 (invalid message) indicate problems that need to be fixed before reconnecting;
5. Logging: Log all errors for debugging and monitoring;
6. Pre-validation: Validate messages before sending to avoid 1008 errors;
7. Timeout Handling: Implement timeout for connections that don’t respond.

​

Exponential Backoff Reconnection Example

let reconnectDelay = 1000; // Start with 1 second
const maxDelay = 60000; // Maximum of 60 seconds

function connect() {
  const ws = new WebSocket('wss://data-ws.voxfi.com.br');
  
  ws.onopen = () => {
    console.log('Connected');
    reconnectDelay = 1000; // Reset delay on success
    // Resubscribe to all channels
    resubscribe(ws);
  };
  
  ws.onclose = (event) => {
    console.log('Connection closed:', event.code);
    
    // Don't reconnect for permanent errors
    if (event.code === 4001 || event.code === 4002 || event.code === 4004) {
      console.error('Permanent error. Fix the problem before reconnecting.');
      return;
    }
    
    // Reconnect with exponential backoff
    setTimeout(() => {
      console.log(`Attempting to reconnect in ${reconnectDelay}ms...`);
      connect();
      reconnectDelay = Math.min(reconnectDelay * 2, maxDelay);
    }, reconnectDelay);
  };
  
  return ws;
}

function resubscribe(ws) {
  // Resubscribe to all channels you were subscribed to
  // Keep a list of active subscriptions
  const subscriptions = [
    { type: 'subscribe', channel: 'market', markets: ['market-id-1'] }
  ];
  
  subscriptions.forEach(sub => {
    ws.send(JSON.stringify(sub));
  });
}