Error handling

Exception hierarchy

Every error the SDK raises for an API call inherits from AesopsError, so a single except AesopsError catches all of them if you don't need to distinguish the cause:

from aesops import AesopsError

try:
    ds = client.load_dataset("does-not-exist")
except AesopsError as e:
    print(f"aesops error: {e}")

NotFoundError

Raised when a dataset (or version) doesn't exist — maps to a 404 from the API:

from aesops import NotFoundError

try:
    ds = client.load_dataset("does-not-exist")
except NotFoundError:
    print("dataset not found")

AuthError

Raised when an API key is missing, invalid, or lacks the required scope — maps to a 401. A key is only required for Dataset.to_pandas() / .to_polars() / .to_duckdb() / .sql() / .to_csv(), and only if the dataset isn't currently keyless; client.list() and load_dataset() never raise this:

from aesops import AuthError

try:
    df = ds.to_pandas()
except AuthError:
    print("invalid or missing API key")

ApiError

Raised for any other non-2xx response. Carries the response's .status_code alongside the message:

from aesops import ApiError

try:
    ds = client.load_dataset("kenya-housing-prices")
except ApiError as e:
    print(f"API error {e.status_code}: {e}")

Catching all three together

from aesops import AuthError, NotFoundError, ApiError

try:
    ds = client.load_dataset("does-not-exist")
except NotFoundError:
    print("dataset not found")
except AuthError:
    print("invalid or missing API key")
except ApiError as e:
    print(f"API error {e.status_code}: {e}")

Errors that aren't AesopsError

A few failure modes come from local usage rather than the API, so they aren't part of the AesopsError hierarchy:

• ImportError — to_pandas()/to_polars()/DescribeTable.to_frame() raise this with an install hint if pandas or polars isn't installed (see Install).
• ValueError — to_pandas(limit=...) / to_polars(limit=...) / to_csv(limit=...) raise this if limit is negative.
• duckdb.IOException — can surface from .sql() / .to_duckdb() for transient network/storage issues reading the underlying Parquet file; the SDK already retries once on an expired/403 signed URL before letting this propagate.

.describe() and .summary() never raise any of the above — they only read metadata load_dataset() already fetched, so they make no network call.