Error handling

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

from minerva import MinervaAPIError

try:
    result = mc.api.enrich(batch)
except MinervaAPIError as e:
    if e.status_code == 402:
        details = (e.body or {}).get("details", {})
        print(f"Minerva credits exhausted. "
              f"~{details.get('records_remaining')} records remaining, "
              f"requested: {details.get('records_requested')}")
    else:
        raise

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)

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}")

from minerva import MinervaValidationError

try:
    mc.api.enrich([])     # 0 records — must be ≥ 1
except MinervaValidationError as e:
    print("caught before any API call:", e)

from minerva import MinervaError

try:
    mc.api.enrich(records)
except MinervaError as e:
    log.error("Minerva call failed", exc_info=e)
    raise