Skip to main content
All SDK exceptions are importable from the top-level package: 
from minerva import (
    MinervaError,                # base
    MinervaConfigError,
    MinervaValidationError,
    MinervaAuthError,
    MinervaRateLimitError,
    MinervaAPIError,
    MinervaWIPWarning,
)

​
MinervaError

Base for everything the SDK raises. Catch this to handle “any SDK failure” without caring about the specific cause.

​
MinervaConfigError(MinervaError)

Misconfiguration — usually surfaces at first call, not at Minerva(...) construction. Fix is always: pass the missing value via constructor arg or env var.

​
MinervaValidationError(MinervaError)

Boundary validation failed — input never left the process. 
try:
    mc.api.enrich([])    # 0 records — must be ≥ 1
except MinervaValidationError as e:
    print(e)
Raised by the request models (pydantic) when input shape is wrong, by mc.api.call() when path is empty / doesn’t start with /, and by every method’s preflight when record counts / required fields fail.

​
MinervaAuthError(MinervaError)

401 / 403 from the server, or no usable credential at all. Common causes:
  • API key missing — MINERVA_API_KEY not set and no api_key= passed
  • API key invalid or revoked
  • Caller not entitled to the endpoint hit (returned by the server-side authorizer)

​
MinervaRateLimitError(MinervaError)

HTTP 429. Attributes:
  • .retry_after — seconds (float) if the server supplied a Retry-After header
try:
    mc.api.enrich(batch)
except MinervaRateLimitError as e:
    time.sleep(e.retry_after or 1)

​
MinervaAPIError(MinervaError)

Any other non-2xx response from the server. Attributes:
  • .status_code — HTTP status (int)
  • .api_request_id — server’s trace ID — quote this when reporting issues
  • .body — parsed response body if available
try:
    mc.api.enrich(records)
except MinervaAPIError as e:
    log.error("Minerva %s: %s", e.status_code, e.api_request_id)

​
MinervaWIPWarning (warning, not an error)

Emitted via warnings.warn when you exercise an SDK feature that ships for forward-compat but isn’t fully GA. The feature still runs; the warning just signals “this isn’t GA, behaviour may change.” Inherits from UserWarning, so the standard warnings machinery applies: 
import warnings
from minerva import MinervaWIPWarning

# Suppress wholesale:
warnings.filterwarnings("ignore", category=MinervaWIPWarning)

# Or turn it into an error to catch every use during development:
warnings.filterwarnings("error", category=MinervaWIPWarning)
No methods currently emit it — it’s exported infrastructure for future use.