Skip to main content
All SDK errors derive from MinervaError. The hierarchy lets you catch broadly (any SDK error) or narrowly (specific failure mode), and most carry context attributes so you can build a useful UI without parsing message strings.

​
The hierarchy

Exception
└── MinervaError                          ← catch-all
    ├── MinervaConfigError                ← misconfiguration
    ├── MinervaValidationError            ← boundary failures, raised locally
    ├── MinervaAuthError                  ← 401/403 (bad key, not entitled)
    ├── MinervaRateLimitError             ← 429.  .retry_after
    └── MinervaAPIError                   ← other 4xx/5xx.  .status_code, .api_request_id, .body

​
Quick reference

ExceptionWhenCarries
MinervaValidationErrorBad input — raised locally, before the call—
MinervaAuthError401/403 — invalid key or not entitled to this endpoint—
MinervaRateLimitError429 — back off and retry.retry_after (seconds)
MinervaAPIErrorOther 4xx/5xx.status_code, .api_request_id, .body
MinervaConfigErrorMisconfiguration—

​
Rate limits

import time
from minerva import MinervaRateLimitError

while True:
    try:
        result = mc.api.enrich(batch)
        break
    except MinervaRateLimitError as e:
        time.sleep(e.retry_after or 1)
retry_after is the server’s hint in seconds. Fall back to a sane default (1s) if the server didn’t supply one.

​
Server errors

from minerva import MinervaAPIError

try:
    mc.api.enrich(records)
except MinervaAPIError as e:
    print(f"server returned {e.status_code}")
    if e.api_request_id:
        print(f"quote to support: {e.api_request_id}")
api_request_id is the server’s trace ID — quote it when reporting issues to support. Responses are forward-compatible: fields the server adds later won’t break an older SDK.

​
Validation errors

MinervaValidationError is raised locally before any HTTP call — bad payload shape, over-the-limit record counts, missing required fields: 
from minerva import MinervaValidationError

try:
    mc.api.enrich([])     # 0 records — must be ≥ 1
except MinervaValidationError as e:
    print("caught before any API call:", e)
Use dry_run=True to trigger the same validation without committing to the call — see Validation & dry_run.

​
Catch-all

from minerva import MinervaError

try:
    mc.api.enrich(records)
except MinervaError as e:
    log.error("Minerva call failed", exc_info=e)
    raise
MinervaAuthError is also raised when no MINERVA_API_KEY is set (or api_key= passed) — that’s a local check, before any HTTP call. The error message tells you exactly what’s missing.