Skip to main content
All SDK exceptions are importable from the top-level package:

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.
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

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
HTTP 402 — Minerva credits exhausted. The .body dict contains records_remaining (an estimate of how many records you have left based on your credit balance) and records_requested (the batch size that was rejected):

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:
No methods currently emit it — it’s exported infrastructure for future use.