Error Taxonomy and Troubleshooting

try {
  await client.memory.add({ user_id: "user@example.com", content: "Hello" });
} catch (error) {
  console.error("Error:", error.code, error.message);
}

interface RetainDBError {
  code: string;          // Error code (e.g., "RATE_LIMITED")
  message: string;       // Human-readable message
  status: number;        // HTTP status code
  trace_id?: string;    // For debugging
  retry_after?: number; // Seconds to wait (for 429)
}

{
  "error": "invalid_api_key",
  "message": "API key is invalid"
}

// Verify key is set correctly
console.log(process.env.RETAINDB_API_KEY);

// Check key format (should start with sk_live_ or sk_test_)
const key = process.env.RETAINDB_API_KEY;
if (!key?.startsWith("sk_")) {
  throw new Error("Invalid key format");
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 60
}

// Implement exponential backoff
async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === "rate_limit_exceeded") {
        const delay = error.retry_after * 1000 || Math.pow(2, i) * 1000;
        console.log(`Rate limited, retrying in ${delay}ms`);
        await new Promise(r => setTimeout(r, delay));
      } else {
        throw error;
      }
    }
  }
}

{
  "error": "invalid_memory_type",
  "message": "Memory type must be one of: factual, preference, event, relationship, opinion, goal, instruction"
}

// Use valid memory types
const validTypes = ["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"];

if (!validTypes.includes(memoryType)) {
  throw new Error(`Invalid memory type: ${memoryType}`);
}

try {
  await client.memory.search({ user_id: "user@example.com", query: "test" });
} catch (error) {
  console.error("Trace ID:", error.trace_id);
  // Contact support with this ID
}

const RETRYABLE_CODES = [
  "NETWORK_ERROR",
  "TIMEOUT",
  "RATE_LIMITED",
  "SERVICE_UNAVAILABLE",
  "INTERNAL_ERROR",
];

const NON_RETRYABLE_CODES = [
  "INVALID_API_KEY",
  "INVALID_REQUEST",
  "NOT_FOUND",
  "PERMISSION_DENIED",
];

async function handleError(error) {
  if (RETRYABLE_CODES.includes(error.code)) {
    // Retry with backoff
    await exponentialBackoff(() => retryOperation());
  } else {
    // Don't retry
    console.error("Non-retryable error:", error.code);
  }
}

async function retryWithJitter(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Exponential backoff with jitter
      const baseDelay = Math.pow(2, i) * 1000;
      const jitter = Math.random() * 1000;
      await new Promise(r => setTimeout(r, baseDelay + jitter));
    }
  }
}

async function healthCheck() {
  try {
    await client.memory.search({
      user_id: "health-check",
      query: "test",
    });
    return { status: "healthy" };
  } catch (error) {
    return { status: "unhealthy", error: error.code };
  }
}

async function detailedHealth() {
  const checks = {
    api: await checkAPI(),
    search: await checkSearch(),
    write: await checkWrite(),
  };

  const allHealthy = Object.values(checks).every(c => c.healthy);
  return { healthy: allHealthy, checks };
}

// Always log with context
console.error({
  timestamp: new Date().toISOString(),
  error_code: error.code,
  error_message: error.message,
  trace_id: error.trace_id,
  user_id: userId,
  operation: "memory.search",
  latency_ms: latency,
});