SDK Error Handling

The SDK provides typed error classes that make it easy to handle different failure modes in your integration.

Error Classes

All errors extend the base GlanceError class. Specific subclasses correspond to HTTP status codes:

Class	Status	Description
`GlanceValidationError`	`400`	Invalid request body or parameters
`GlanceAuthenticationError`	`401 / 403`	Missing or invalid API key
`GlanceNotFoundError`	`404`	Resource does not exist
`GlanceRateLimitError`	`429`	Rate limit exceeded
`GlanceApiError`	`any`	Base class for all API errors

Catching Errors

TypeScript

import {
  GlanceClient,
  GlanceApiError,
  GlanceAuthenticationError,
  GlanceNotFoundError,
  GlanceValidationError,
  GlanceRateLimitError,
} from "@glance-il/sdk";

const glance = new GlanceClient({
  apiKey: process.env.GLANCE_API_KEY!,
});

try {
  const { data } = await glance.clients.get(999);
} catch (error) {
  if (error instanceof GlanceNotFoundError) {
    console.error("Client not found");
  } else if (error instanceof GlanceValidationError) {
    console.error("Validation failed:", error.message);
  } else if (error instanceof GlanceAuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof GlanceRateLimitError) {
    console.error("Rate limited — retry after", error.retryAfter, "ms");
  } else if (error instanceof GlanceApiError) {
    console.error(`API Error ${error.status}: ${error.message}`);
  }
}

Validation Errors

GlanceValidationError includes an issues array with field-level details:

TypeScript

try {
  await glance.clients.create({ name: "" });
} catch (error) {
  if (error instanceof GlanceValidationError) {
    for (const issue of error.issues) {
      console.error(`${issue.field}: ${issue.message}`);
    }
  }
}

Rate Limit Handling

When rate limited, GlanceRateLimitError includes a retryAfter property (in milliseconds):

TypeScript

async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
  try {
    return await fn();
  } catch (error) {
    if (error instanceof GlanceRateLimitError && error.retryAfter) {
      await new Promise((r) => setTimeout(r, error.retryAfter));
      return fn();
    }
    throw error;
  }
}

const { data } = await withRetry(() => glance.clients.list());

TypeScript Types

All request and response types are exported for full type safety:

TypeScript

import type {
  Client,
  CreateClientParams,
  GlanceDocument,
  CreateDocumentParams,
  Product,
  PaginationMeta,
} from "@glance-il/sdk";

function processClient(client: Client): void {
  console.log(`${client.name} — ${client.email}`);
}