Skip to main content
All Lucid API errors follow a consistent format with actionable error codes.

​
Error Format

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 30 seconds.",
    "status": 429,
    "details": { "retryAfter": 30 }
  }
}

​
SDK Error Handling

import { LucidAI } from "raijin-labs-lucid-ai";

const lucid = new LucidAI({ bearerAuth: process.env.LUCID_API_KEY });

try {
  const result = await lucid.chat.completions({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }]
  });
} catch (error) {
  switch (error.status) {
    case 401:
      console.error("Invalid API key");
      break;
    case 429:
      // Rate limited — exponential backoff
      const delay = error.details?.retryAfter || 30;
      await new Promise(r => setTimeout(r, delay * 1000));
      break;
    case 503:
      // Model unavailable — try fallback
      console.error("Model unavailable, trying fallback...");
      break;
    default:
      console.error(`Error ${error.status}: ${error.message}`);
  }
}

​
Retry Pattern

async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
}

const result = await withRetry(() =>
  lucid.chat.completions({ model: "gpt-4o", messages: [...] })
);
See the full Error Reference for all error codes.