Error Codes

{
  "error": "rate_limited",
  "message": "Too many requests. Please wait before trying again.",
  "retryAfterSeconds": 12,
  "retryable": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Server JSON Response          →  SDK AtlasError
─────────────────────          ──────────────────
{ error: "rate_limited" }     →  error.code = "rate_limited"
{ message: "Too many..." }    →  error.message = "Too many..."
HTTP 429                       →  error.status = 429
{ retryable: true }           →  error.retryable = true
{ retryAfterSeconds: 12 }    →  error.retryAfterSeconds = 12

import { AtlasError, createAtlasClient, type QueryResponse } from "@useatlas/sdk";

const atlas = createAtlasClient({
  baseUrl: "https://api.example.com",
  apiKey: "your-api-key",
});

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

async function queryWithRetry(
  question: string,
  maxRetries = 3,
): Promise<QueryResponse> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await atlas.query(question);
    } catch (error) {
      if (!(error instanceof AtlasError)) throw error;

      // Permanent error — retrying won't help
      if (!error.retryable) throw error;

      // Last attempt — no more retries
      if (attempt === maxRetries) throw error;

      // Rate limited — use the server-provided delay
      if (error.code === "rate_limited" && error.retryAfterSeconds) {
        console.log(`Rate limited — waiting ${error.retryAfterSeconds}s`);
        await sleep(error.retryAfterSeconds * 1000);
        continue;
      }

      // Other transient errors — exponential backoff
      const delay = Math.min(1000 * 2 ** attempt, 30_000);
      console.log(`${error.code} — retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
      await sleep(delay);
    }
  }

  // Unreachable, but satisfies TypeScript
  throw new Error("Retry loop exited unexpectedly");
}

try {
  await atlas.query("Revenue by region");
} catch (error) {
  if (!(error instanceof AtlasError)) throw error;

  switch (error.code) {
    case "auth_error":
    case "session_expired":
      // Redirect to login or prompt for a new API key
      redirectToLogin();
      break;
    case "forbidden_role":
      // User doesn't have admin access
      showPermissionDenied(error.message);
      break;
    case "configuration_error":
    case "no_datasource":
      // Show setup instructions — the server isn't ready
      showSetupGuide(error.message);
      break;
    case "provider_model_not_found":
    case "provider_auth_error":
      // Admin needs to fix server config
      showAdminAlert(error.message);
      break;
    default:
      if (error.retryable) {
        // Generic transient error — show retry UI
        showRetryButton(error.message);
      } else {
        // Permanent error — show the message to the user
        showError(error.message);
      }
  }
}