Error Codes

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description of what went wrong",
    "details": {
      // Optional additional context
    },
    "request_id": "req_abc123xyz"
  }
}

import { Trix, TrixError, RateLimitError, ValidationError } from '@trixdb/client';

const trix = new Trix({ apiKey: process.env.TRIX_API_KEY });

async function createMemory(content: string) {
  try {
    const memory = await trix.memories.create({ content });
    return memory;
  } catch (error) {
    if (error instanceof RateLimitError) {
      // Rate limited - wait and retry
      console.log(`Rate limited. Retry after ${error.retryAfter}s`);
      await sleep(error.retryAfter * 1000);
      return createMemory(content); // Retry
    }

    if (error instanceof ValidationError) {
      // Validation failed - log field errors
      console.error('Validation failed:', error.fields);
      throw error; // Don't retry
    }

    if (error instanceof TrixError) {
      // Other API error
      console.error(`API Error [${error.code}]: ${error.message}`);
      console.error(`Request ID: ${error.requestId}`);

      if (error.statusCode >= 500) {
        // Server error - safe to retry
        await sleep(1000);
        return createMemory(content);
      }

      throw error;
    }

    throw error;
  }
}

function sleep(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "fields": {
        "content": {
          "code": "required",
          "message": "Content is required"
        },
        "priority": {
          "code": "invalid_range",
          "message": "Priority must be between 0 and 10",
          "received": 15,
          "min": 0,
          "max": 10
        },
        "tags": {
          "code": "invalid_type",
          "message": "Tags must be an array of strings",
          "received": "string"
        }
      }
    },
    "request_id": "req_validation_abc123"
  }
}

if (error instanceof ValidationError) {
  for (const [field, details] of Object.entries(error.fields)) {
    switch (details.code) {
      case 'required':
        console.log(`Missing required field: ${field}`);
        break;
      case 'invalid_range':
        console.log(`${field} must be between ${details.min} and ${details.max}`);
        break;
      case 'invalid_type':
        console.log(`${field} has wrong type, got ${details.received}`);
        break;
      default:
        console.log(`${field}: ${details.message}`);
    }
  }
}

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800
Retry-After: 30

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "details": {
      "limit": 300,
      "remaining": 0,
      "reset": 1705312800,
      "retry_after": 30,
      "window": 60
    },
    "request_id": "req_rate_xyz789"
  }
}

interface RetryConfig {
  maxRetries: number;
  baseDelay: number;
  maxDelay: number;
  retryableErrors: string[];
}

const defaultConfig: RetryConfig = {
  maxRetries: 3,
  baseDelay: 1000,
  maxDelay: 30000,
  retryableErrors: [
    'rate_limit_exceeded',
    'internal_error',
    'storage_error',
    'service_unavailable'
  ]
};

async function withRetry<T>(
  fn: () => Promise<T>,
  config = defaultConfig
): Promise<T> {
  let lastError: Error;

  for (let attempt = 0; attempt < config.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;

      if (error instanceof TrixError) {
        if (!config.retryableErrors.includes(error.code)) {
          throw error;
        }

        const retryAfter = error.details?.retry_after;
        if (retryAfter) {
          await sleep(retryAfter * 1000);
          continue;
        }
      }

      const delay = Math.min(
        config.baseDelay * Math.pow(2, attempt) + Math.random() * 1000,
        config.maxDelay
      );

      console.log(`Retry attempt ${attempt + 1} in ${delay}ms`);
      await sleep(delay);
    }
  }

  throw lastError!;
}

# Run diagnostics
trix doctor

# Enable verbose logging
TRIX_DEBUG=true trix recall "test query"

# Check a specific request
curl -v -H "Authorization: Bearer $TRIX_API_KEY" \
  https://api.trixdb.com/v1/memories/mem_abc123