[P1][DX] Normalize API error shapes into one typed Python exception model

[karlwaldman]

Problem

The live V1 API still has canonical and legacy error envelopes. Until OilpriceAPI/oilpriceapi-api#4083 completes, Python callers should not need endpoint-specific parsing.

Required outcome

Every non-2xx response becomes one stable typed SDK exception while preserving raw diagnostics.

Acceptance criteria

• Typed model includes HTTP status, machine code, message, request ID, docs URL, current plan, required plan/feature, remediation URL, retry metadata, and raw body.
• Parse the canonical nested error object.
• Normalize legacy flat error, error_code, code, message, and malformed/non-JSON bodies.
• Useful subclasses or predicates for 400/401/402/403/404/429/5xx without losing the shared base contract.
• Preserve headers and raw text for support output; never include the API key.
• Cover canonical/legacy fixtures plus timeout/network failures.
• Update README/reference examples with safe recovery and request-ID reporting.
• Pin contract fixtures so compatibility branches can be deleted after backend migration.

Priority

P1 developer trust. Source: CX Fix Punch List, 2026-07-17.

[karlwaldman]

Portfolio review, 2026-07-19: schedule this in Sprint 1 of OilpriceAPI/oilpriceapi-docs#115 alongside oilpriceapi-node#47 and api#4792. Typed exceptions must preserve status, request ID when supplied, retryability, plan/quota guidance, and raw safe response details; include fixtures for 400, 401, 402, 403, 404, 429, and 5xx.