Common Issues

This guide covers the most frequently encountered issues when using the Axiom Trade Rust client and their solutions.

Authentication Failures

Invalid Login Credentials

Problem: Login fails with "Invalid credentials" error.

Solutions:

1. Verify credentials: Double-check your email and password
2. Check password hashing: Ensure you're using the correct PBKDF2 implementation with 600,000 iterations
3. Account status: Verify your account is active and not suspended
4. Case sensitivity: Email addresses are case-sensitive in some systems

#![allow(unused)]
fn main() {
// Correct password hashing example
use pbkdf2::{password_hash::{PasswordHasher, SaltString}, Pbkdf2};

let salt = SaltString::generate(&mut OsRng);
let password_hash = Pbkdf2.hash_password_customized(
    password.as_bytes(),
    Some(pbkdf2::password_hash::Ident::new("pbkdf2")?),
    None,
    pbkdf2::Params {
        rounds: 600_000,
        output_length: 32,
    },
    &salt,
)?;
}

OTP Verification Issues

Problem: OTP verification fails or times out.

Solutions:

1. Time synchronization: Ensure your system clock is accurate
2. OTP expiration: Use the OTP within 5 minutes of receipt
3. Email delivery: Check spam folder for OTP emails
4. Automated OTP setup: Configure inbox.lv automation for seamless OTP handling

#![allow(unused)]
fn main() {
// Enable automated OTP fetching
std::env::set_var("INBOX_LV_EMAIL", "your_email@inbox.lv");
std::env::set_var("INBOX_LV_PASSWORD", "your_imap_password");
}

Token Expiration

Problem: API calls fail with "Token expired" error.

Solutions:

1. Automatic refresh: Implement token refresh logic
2. Token storage: Persist tokens securely between sessions
3. Expiration monitoring: Check token expiry before making API calls

#![allow(unused)]
fn main() {
// Token refresh example
if token_manager.is_expired() {
    token_manager.refresh_token().await?;
}
}

Connection Issues

Network Timeouts

Problem: Requests timeout or fail to connect.

Solutions:

1. Increase timeout: Set appropriate timeout values for your network
2. Retry logic: Implement exponential backoff for failed requests
3. Network connectivity: Check internet connection and DNS resolution
4. Firewall settings: Ensure Axiom Trade endpoints are not blocked

#![allow(unused)]
fn main() {
// Configure client with proper timeouts
let client = reqwest::Client::builder()
    .timeout(Duration::from_secs(30))
    .connect_timeout(Duration::from_secs(10))
    .build()?;
}

SSL/TLS Errors

Problem: SSL certificate verification failures.

Solutions:

1. Certificate validation: Ensure system certificates are up to date
2. TLS version: Use TLS 1.2 or higher
3. Corporate proxies: Configure proxy settings if behind corporate firewall
4. Certificate pinning: Implement certificate pinning for enhanced security

DNS Resolution Issues

Problem: Cannot resolve Axiom Trade domain names.

Solutions:

1. DNS servers: Try different DNS servers (8.8.8.8, 1.1.1.1)
2. Hosts file: Check for incorrect entries in hosts file
3. Network configuration: Verify network adapter settings
4. VPN interference: Disable VPN temporarily to test connectivity

Rate Limit Errors

HTTP 429 Too Many Requests

Problem: API returns rate limit exceeded errors.

Solutions:

1. Request spacing: Implement delays between API calls
2. Rate limiter: Use built-in rate limiting functionality
3. Batch operations: Combine multiple operations into batch requests
4. Retry-After header: Respect the Retry-After header in responses

#![allow(unused)]
fn main() {
// Rate limiting example
use std::time::{Duration, Instant};

struct RateLimiter {
    last_request: Instant,
    min_interval: Duration,
}

impl RateLimiter {
    fn wait_if_needed(&mut self) {
        let elapsed = self.last_request.elapsed();
        if elapsed < self.min_interval {
            std::thread::sleep(self.min_interval - elapsed);
        }
        self.last_request = Instant::now();
    }
}
}

Burst Rate Limits

Problem: Hitting burst limits with rapid successive requests.

Solutions:

1. Queue requests: Implement request queuing system
2. Parallel limits: Limit concurrent requests
3. Request prioritization: Prioritize critical operations
4. Caching: Cache frequently requested data

API Quota Exhaustion

Problem: Daily or monthly API quotas exceeded.

Solutions:

1. Usage monitoring: Track API usage against quotas
2. Efficient queries: Optimize queries to reduce API calls
3. Data caching: Cache responses to avoid repeated requests
4. Upgrade plan: Consider upgrading to higher tier plan

WebSocket Disconnections

Connection Drops

Problem: WebSocket connections frequently disconnect.

Solutions:

1. Keepalive: Implement ping/pong keepalive mechanism
2. Reconnection logic: Automatic reconnection with exponential backoff
3. Connection monitoring: Monitor connection health
4. Network stability: Check network connection stability

// WebSocket reconnection example
async fn maintain_websocket_connection(mut ws: WebSocket) -> Result<()> {
    let mut reconnect_attempts = 0;
    const MAX_RECONNECT_ATTEMPTS: u32 = 5;
    
    loop {
        match ws.next().await {
            Some(Ok(message)) => {
                // Handle message
                reconnect_attempts = 0; // Reset on successful message
            }
            Some(Err(e)) => {
                log::error!("WebSocket error: {}", e);
                if reconnect_attempts < MAX_RECONNECT_ATTEMPTS {
                    let delay = Duration::from_secs(2_u64.pow(reconnect_attempts));
                    tokio::time::sleep(delay).await;
                    ws = reconnect_websocket().await?;
                    reconnect_attempts += 1;
                } else {
                    return Err(e.into());
                }
            }
            None => {
                // Connection closed
                break;
            }
        }
    }
    Ok(())
}

Authentication Timeout

Problem: WebSocket authentication times out.

Solutions:

1. Token validation: Ensure tokens are valid before connecting
2. Authentication timing: Send auth message immediately after connection
3. Connection timeout: Increase authentication timeout
4. Session management: Maintain valid session tokens

Message Processing Delays

Problem: WebSocket messages arrive with delays or out of order.

Solutions:

1. Message buffering: Implement proper message buffering
2. Sequence numbers: Use sequence numbers for message ordering
3. Timestamp validation: Validate message timestamps
4. Processing optimization: Optimize message processing speed

Environment Configuration Problems

Missing Environment Variables

Problem: Application fails to start due to missing configuration.

Solutions:

1. Environment file: Create .env file with required variables
2. Variable validation: Check all required variables at startup
3. Default values: Provide sensible defaults where possible
4. Configuration templates: Use configuration templates

# Required environment variables
AXIOM_EMAIL=your_email@example.com
AXIOM_PASSWORD=your_password
INBOX_LV_EMAIL=your_email@inbox.lv
INBOX_LV_PASSWORD=your_imap_password
RUST_LOG=info

Incorrect API Endpoints

Problem: API calls fail due to wrong endpoint URLs.

Solutions:

1. Environment configuration: Use environment variables for endpoints
2. Endpoint validation: Validate endpoints at startup
3. Version compatibility: Ensure using correct API version
4. Documentation reference: Check latest API documentation

Permission Issues

Problem: File system permission errors.

Solutions:

1. File permissions: Set correct permissions for config files
2. Directory access: Ensure application has access to required directories
3. User privileges: Run with appropriate user privileges
4. Security contexts: Configure security contexts properly

Configuration File Issues

Problem: Configuration files not loading or parsing errors.

Solutions:

1. File format: Verify correct TOML/JSON/YAML format
2. File location: Check configuration file paths
3. Encoding: Ensure files are UTF-8 encoded
4. Syntax validation: Validate configuration syntax

#![allow(unused)]
fn main() {
// Configuration validation example
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize)]
struct Config {
    #[serde(default = "default_timeout")]
    timeout: u64,
    #[serde(default = "default_retries")]
    max_retries: u32,
    api_endpoint: String,
}

fn default_timeout() -> u64 { 30 }
fn default_retries() -> u32 { 3 }

impl Config {
    fn validate(&self) -> Result<(), ConfigError> {
        if self.api_endpoint.is_empty() {
            return Err(ConfigError::MissingApiEndpoint);
        }
        if self.timeout == 0 {
            return Err(ConfigError::InvalidTimeout);
        }
        Ok(())
    }
}
}

General Troubleshooting Tips

Enable Debug Logging

Set the RUST_LOG environment variable to get detailed logs:

export RUST_LOG=debug
# or for specific modules
export RUST_LOG=axiomtrade_rs=debug,reqwest=info

Check System Requirements

Ensure your system meets the minimum requirements:

• Rust 1.70 or higher
• OpenSSL development libraries
• Stable internet connection
• Sufficient disk space for logs and cache

Update Dependencies

Keep dependencies updated to the latest compatible versions:

cargo update
cargo audit

Monitor Resource Usage

Monitor system resources during operation:

• Memory usage
• CPU utilization
• Network bandwidth
• Disk I/O

Contact Support

If issues persist after following this guide:

1. Collect relevant logs with debug level enabled
2. Document exact error messages and reproduction steps
3. Include system information and version details
4. Contact support through official channels