Error Handling

Overview

The Xtrix API uses standard HTTP response codes to indicate the success or failure of an API request. In general:

2xx codes indicate success
4xx codes indicate an error with the request
5xx codes indicate an error with our servers

Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "message": "Human-readable error message",
    "type": "error_category",
    "code": "specific_error_code",
    "param": "field_name" // Optional: which parameter caused the error
  }
}

Common Error Codes

400 Bad Request

Invalid request format or parameters.

{
  "error": {
    "message": "Invalid request body",
    "type": "invalid_request_error",
    "code": "invalid_body"
  }
}

Common causes:

Malformed JSON
Missing required parameters
Invalid parameter values
Unsupported parameter combinations

401 Unauthorized

Authentication failed.

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Common causes:

Missing API key
Invalid API key
Revoked API key
Incorrect authentication format

402 Payment Required

Insufficient credits or payment issues.

{
  "error": {
    "message": "Insufficient credits. Please purchase more credits to continue using the API.",
    "type": "insufficient_credits_error",
    "code": "insufficient_credits"
  }
}

Common causes:

Account has no remaining credits
Subscription expired
Payment method failed

429 Too Many Requests

Rate limit exceeded.

{
  "error": {
    "message": "Rate limit exceeded. Free users are limited to 10 requests per minute.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "retry_after": 45
  }
}

Common causes:

Too many requests in a short time
Exceeding your tier’s rate limit (10 req/min for free, 20 req/min for pro)

Rate limit details:

Uses a sliding window algorithm
Limits are per API key
The retry_after field indicates seconds until you can retry

500 Internal Server Error

Server-side error.

{
  "error": {
    "message": "An internal error occurred. Please try again.",
    "type": "api_error",
    "code": "internal_error"
  }
}

Common causes:

Temporary server issues
Unexpected server errors
Service maintenance

Error Types Reference

Type	Description	HTTP Status
`invalid_request_error`	Invalid request parameters	400
`authentication_error`	Authentication failed	401
`insufficient_credits_error`	Payment/credit issues	402
`permission_error`	Insufficient permissions	403
`not_found_error`	Resource not found	404
`rate_limit_error`	Rate limit exceeded	429
`api_error`	Server error	500+

Handling Errors

Python Error Handling

from openai import OpenAI
import time

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.xtrix.workers.dev/v1"
)

def safe_api_call(func, *args, **kwargs):
    max_retries = 3
    retry_delay = 1

    for attempt in range(max_retries):
        try:
            return func(*args, **kwargs)
        except Exception as e:
            error_message = str(e)

            # Handle different error types
            if hasattr(e, 'status'):
                if e.status == 401:
                    print("Authentication error. Check your API key.")
                    raise
                elif e.status == 402:
                    print("Insufficient credits. Please add credits to your account.")
                    raise
                elif e.status == 429:
                    # Rate limited - implement exponential backoff
                    wait_time = retry_delay * (2 ** attempt)
                    print(f"Rate limited. Waiting {wait_time} seconds...")
                    time.sleep(wait_time)
                    continue
                elif e.status >= 500:
                    # Server error - retry
                    if attempt < max_retries - 1:
                        print(f"Server error. Retrying in {retry_delay} seconds...")
                        time.sleep(retry_delay)
                        continue

            # If we can't handle it, re-raise
            raise

    raise Exception("Max retries exceeded")

# Usage
try:
    response = safe_api_call(
        client.chat.completions.create,
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except Exception as e:
    print(f"Failed to complete request: {e}")

JavaScript Error Handling

class APIError extends Error {
  constructor(message, status, type, code) {
    super(message);
    this.status = status;
    this.type = type;
    this.code = code;
  }
}

async function safeAPICall(apiFunc, ...args) {
  const maxRetries = 3;
  let retryDelay = 1000;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await apiFunc(...args);
    } catch (error) {
      // Parse error details
      const status = error.status || 500;
      const errorData = error.response?.data?.error || {};

      // Handle different error types
      switch (status) {
        case 401:
          throw new APIError(
            'Authentication failed. Check your API key.',
            401,
            'authentication_error',
            errorData.code
          );

        case 402:
          throw new APIError(
            'Insufficient credits. Please add credits.',
            402,
            'insufficient_credits_error',
            errorData.code
          );

        case 429:
          // Rate limited - exponential backoff
          const waitTime = retryDelay * Math.pow(2, attempt);
          console.log(`Rate limited. Waiting ${waitTime}ms...`);
          await new Promise((resolve) => setTimeout(resolve, waitTime));
          continue;

        case 500:
        case 502:
        case 503:
          // Server errors - retry
          if (attempt < maxRetries - 1) {
            console.log(`Server error. Retrying in ${retryDelay}ms...`);
            await new Promise((resolve) => setTimeout(resolve, retryDelay));
            continue;
          }
          break;
      }

      // Can't handle this error
      throw error;
    }
  }

  throw new Error('Max retries exceeded');
}

// Usage
try {
  const response = await safeAPICall(
    openai.chat.completions.create.bind(openai),
    {
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: 'Hello!' }],
    }
  );
} catch (error) {
  console.error('Failed to complete request:', error.message);
}

Error Recovery Strategies

1. Exponential Backoff

Gradually increase wait time between retries:

def exponential_backoff(attempt, base_delay=1, max_delay=60):
    """Calculate delay with exponential backoff and jitter"""
    delay = min(base_delay * (2 ** attempt), max_delay)
    jitter = random.uniform(0, delay * 0.1)  # 10% jitter
    return delay + jitter

2. Circuit Breaker Pattern

Prevent cascading failures:

class CircuitBreaker {
  constructor(threshold = 5, timeout = 60000) {
    this.failureCount = 0;
    this.threshold = threshold;
    this.timeout = timeout;
    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
    this.nextAttempt = Date.now();
  }

  async call(func, ...args) {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextAttempt) {
        throw new Error('Circuit breaker is OPEN');
      }
      this.state = 'HALF_OPEN';
    }

    try {
      const result = await func(...args);
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }

  onFailure() {
    this.failureCount++;
    if (this.failureCount >= this.threshold) {
      this.state = 'OPEN';
      this.nextAttempt = Date.now() + this.timeout;
    }
  }
}

3. Fallback Responses

Provide degraded functionality:

def get_response_with_fallback(prompt, model="gpt-3.5-turbo"):
    models = ["gpt-3.5-turbo", "gpt-3.5-turbo-16k", "gpt-4"]

    for fallback_model in models:
        try:
            return client.chat.completions.create(
                model=fallback_model,
                messages=[{"role": "user", "content": prompt}]
            )
        except Exception as e:
            if hasattr(e, 'status') and e.status == 400:
                # Model not available, try next
                continue
            else:
                # Other error, re-raise
                raise

    # All models failed
    raise Exception("All models unavailable")

Best Practices

1. Always Handle Errors

Never assume API calls will succeed:

# Bad
response = client.chat.completions.create(...)
print(response.choices[0].message.content)

# Good
try:
    response = client.chat.completions.create(...)
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Error: {e}")
    # Handle appropriately

2. Log Errors for Debugging

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

try:
    response = make_api_call()
except Exception as e:
    logger.error(f"API call failed: {e}", exc_info=True)
    # Include request details for debugging
    logger.error(f"Request params: {request_params}")

3. Implement Retry Logic

const retry = async (fn, retries = 3, delay = 1000) => {
  try {
    return await fn();
  } catch (error) {
    if (retries === 0) throw error;

    // Only retry on retryable errors
    const retryableStatuses = [429, 500, 502, 503, 504];
    if (!retryableStatuses.includes(error.status)) {
      throw error;
    }

    await new Promise((resolve) => setTimeout(resolve, delay));
    return retry(fn, retries - 1, delay * 2);
  }
};

4. Validate Input Before Sending

def validate_messages(messages):
    """Validate messages before API call"""
    if not messages:
        raise ValueError("Messages cannot be empty")

    for msg in messages:
        if 'role' not in msg or 'content' not in msg:
            raise ValueError("Each message must have 'role' and 'content'")

        if msg['role'] not in ['system', 'user', 'assistant']:
            raise ValueError(f"Invalid role: {msg['role']}")

    return True

Error Monitoring

Track Error Rates

from collections import defaultdict
from datetime import datetime, timedelta

class ErrorMonitor:
    def __init__(self):
        self.errors = defaultdict(list)

    def log_error(self, error_type, error_code):
        self.errors[error_type].append({
            'code': error_code,
            'timestamp': datetime.now()
        })
        self.cleanup_old_errors()

    def cleanup_old_errors(self):
        cutoff = datetime.now() - timedelta(hours=24)
        for error_type in self.errors:
            self.errors[error_type] = [
                e for e in self.errors[error_type]
                if e['timestamp'] > cutoff
            ]

    def get_error_stats(self):
        stats = {}
        for error_type, errors in self.errors.items():
            stats[error_type] = {
                'count': len(errors),
                'recent': len([e for e in errors
                             if e['timestamp'] > datetime.now() - timedelta(hours=1)])
            }
        return stats

Common Troubleshooting

Error	Likely Cause	Solution
`invalid_api_key`	Wrong or revoked key	Check dashboard for valid key
`model_not_found`	Invalid model name	Use `/models` endpoint to list available
`context_length_exceeded`	Input too long	Reduce input size or use different model
`insufficient_credits`	No credits remaining	Purchase credits in dashboard
`rate_limit_exceeded`	Too many requests	Implement backoff and queuing

Getting Help

If you encounter persistent errors:

Check the error message and code
Verify your API key and account status
Review the API documentation
Contact support@xtrix.tech with:
- Error message and code
- Request ID (if available)
- Code snippet reproducing the issue
- Timestamp of the error

Remember: Good error handling makes your application more robust and provides better user experience.

Overview

Endpoints

​Overview

​Error Response Format

​Common Error Codes

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​429 Too Many Requests

​500 Internal Server Error

​Error Types Reference

​Handling Errors

​Python Error Handling

​JavaScript Error Handling

​Error Recovery Strategies

​1. Exponential Backoff

​2. Circuit Breaker Pattern

​3. Fallback Responses

​Best Practices

​1. Always Handle Errors

​2. Log Errors for Debugging

​3. Implement Retry Logic

​4. Validate Input Before Sending

​Error Monitoring

​Track Error Rates

​Common Troubleshooting

​Getting Help

Overview

Error Response Format

Common Error Codes

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

500 Internal Server Error

Error Types Reference

Handling Errors

Python Error Handling

JavaScript Error Handling

Error Recovery Strategies

1. Exponential Backoff

2. Circuit Breaker Pattern

3. Fallback Responses

Best Practices

1. Always Handle Errors

2. Log Errors for Debugging

3. Implement Retry Logic

4. Validate Input Before Sending

Error Monitoring

Track Error Rates

Common Troubleshooting

Getting Help