Error Handling — Elephantasm Docs

Error Classes

Both SDKs provide typed error classes for common failure scenarios:

from elephantasm import inject
from elephantasm.exceptions import (
  AuthenticationError,  # 401 - Invalid API key
  NotFoundError,        # 404 - Anima not found
  RateLimitError,       # 429 - Too many requests
  ValidationError,      # 422 - Invalid parameters
  ServerError,          # 5xx - Server error
)

try:
  pack = inject()
except AuthenticationError:
  print("Check your ELEPHANTASM_API_KEY")
except NotFoundError:
  print("Anima not found - check ELEPHANTASM_ANIMA_ID")
except RateLimitError:
  print("Rate limited - retry later")

Error Reference

Name	Type	Required	Description
AuthenticationError	401	optional	Invalid or missing API key. Check ELEPHANTASM_API_KEY.
NotFoundError	404	optional	Anima not found. Check ELEPHANTASM_ANIMA_ID or the anima_id parameter.
ValidationError	422	optional	Invalid parameters (wrong types, missing required fields).
RateLimitError	429	optional	Too many requests. Back off and retry with exponential delay.
ServerError	5xx	optional	Server-side error. Retry after a brief delay.

Null Pack Handling

inject() returns null (TypeScript) or None (Python) when no memory packs exist — for example, for a new anima with no events yet. Always check before accessing pack methods:

pack = inject()
if pack:
  prompt = pack.as_prompt()
else:
  prompt = ""  # No memories yet

A null pack is normal for new animas. Your agent should work without memory context and build it over time.

Retry Strategy

For production applications, wrap SDK calls with retry logic:

import time
from elephantasm import inject
from elephantasm.exceptions import RateLimitError, ServerError

def inject_with_retry(max_retries=3):
  for attempt in range(max_retries):
      try:
          return inject()
      except RateLimitError:
          time.sleep(2 ** attempt)  # Exponential backoff
      except ServerError:
          time.sleep(1)
  return None