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
        └── MinervaInsufficientCreditsError ← 402 record export capacity failure.  .code, .details

from minerva import MinervaInsufficientCreditsError

try:
    result = mc.api.enrich(batch)
except MinervaInsufficientCreditsError as error:
    details = error.details or {}
    print(f"Available records: {details.get('records_available')}; "
          f"requested: {details.get('records_requested')}")

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