All error classes are importable from the package:

import {
  ElephantasmError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
} from "@elephantasm/client";

Hierarchy

ElephantasmError (extends Error)
├── AuthenticationError  (401)
├── NotFoundError        (404)
├── ValidationError      (422)
├── RateLimitError       (429)
└── ServerError          (5xx)

All errors extend ElephantasmError, which extends the native Error class. Each subclass sets Object.setPrototypeOf for proper instanceof support.

ElephantasmError

Base error for all SDK errors. Catch this to handle any Elephantasm error generically.

import { inject, ElephantasmError } from "@elephantasm/client";
 
try {
  const pack = await inject();
} catch (error) {
  if (error instanceof ElephantasmError) {
    console.error(`Error (${error.statusCode}): ${error.message}`);
  }
}

AuthenticationError

Thrown on 401 responses. Invalid, missing, or expired API key.

When thrown:

• No API key provided and ELEPHANTASM_API_KEY not set
• API key is invalid or revoked
• API key has expired

NotFoundError

Thrown on 404 responses. The requested resource does not exist.

When thrown:

• animaId doesn't exist or was deleted
• Resource belongs to a different user (RLS isolation)

ValidationError

Thrown on 422 responses. Request parameters failed server-side validation.

When thrown:

• Missing required fields (eventType, content)
• importanceScore outside 0.0–1.0 range
• Invalid enum values

RateLimitError

Thrown on 429 responses. Too many requests or plan usage limit exceeded.

When thrown:

• Too many API requests in a short period
• Monthly event or pack limit reached for your plan

ServerError

Thrown on 5xx responses. An unexpected error occurred on the Elephantasm backend.

When thrown:

• Internal server errors
• Temporary service disruptions

Error Handling Pattern

Use instanceof to catch specific errors:

import { extract } from "@elephantasm/client";
import {
  AuthenticationError,
  RateLimitError,
  ElephantasmError,
} from "@elephantasm/client";
 
try {
  await extract("message.in", "Hello!", { role: "user" });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Check your API key");
  } else if (error instanceof RateLimitError) {
    console.error("Slow down — retry after a delay");
  } else if (error instanceof ElephantasmError) {
    console.error(`Unexpected error (${error.statusCode}): ${error.message}`);
  }
}