Python: Exceptions — Elephantasm Docs

All exceptions are importable from the top-level package:

from elephantasm import (
    ElephantasmError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ServerError,
)

Hierarchy

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

All exceptions extend ElephantasmError, which extends Python's built-in Exception.

ElephantasmError

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

Name	Type	Required	Description
message	str	required	Human-readable error description.
status_code	int \| None	optional	HTTP status code that triggered the error, if applicable.

from elephantasm import inject, ElephantasmError
 
try:
    pack = inject()
except ElephantasmError as e:
    print(f"Error ({e.status_code}): {e.message}")

AuthenticationError

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

Property	Value
`status_code`	`401`
Default message	`"Authentication failed"`

When raised:

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

NotFoundError

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

Property	Value
`status_code`	`404`
Default message	`"Resource not found"`

When raised:

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

ValidationError

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

Property	Value
`status_code`	`422`
Default message	`"Validation failed"`

When raised:

Missing required fields (event_type, content)
importance_score outside 0.0–1.0 range
name exceeds 255 characters
Invalid enum values

RateLimitError

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

Property	Value
`status_code`	`429`
Default message	`"Rate limit exceeded"`

When raised:

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

See Error Handling for retry strategies with exponential backoff.

ServerError

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

Property	Value
`status_code`	`500`
Default message	`"Server error"`

When raised:

Internal server errors
Temporary service disruptions

Catching Specific Errors

from elephantasm import extract, EventType
from elephantasm import AuthenticationError, RateLimitError, ElephantasmError
 
try:
    extract(EventType.MESSAGE_IN, "Hello!", role="user")
except AuthenticationError:
    print("Check your API key")
except RateLimitError:
    print("Slow down — retry after a delay")
except ElephantasmError as e:
    print(f"Unexpected error ({e.status_code}): {e.message}")

For practical error handling patterns including retry logic and null pack handling, see the Error Handling guide.