PDFCLOUD-5695 Expect error detail response field

[datalogics-cgreen]

PDFCLOUD-5695

Why this change

pdfRest error responses now include richer validation data (errorDetail.issues), but the SDK was only reading a single message field and could miss that structure entirely. In practice, callers often got a generic status-code error and had to inspect raw payloads manually to find which input field failed.

This change improves developer feedback loops: invalid request payloads are now easier to diagnose, and error handling code can access structured issue details instead of relying on string parsing.

What changed (high level)

The error parsing path was updated to support both legacy and current server message keys (message and error) and to model structured error details explicitly. We introduced typed models for errorDetail/issues, exported them from pdfrest.models, and updated response extraction so structured details are preserved on raised API exceptions.

The main tradeoff is intentional: we now prioritize structured payload preservation when available, which increases fidelity for callers but changes some response_content expectations in existing integrations. Package version was bumped to 1.1.0 to reflect this behavior expansion.

Behavior changes

At runtime, API errors now behave differently in a few important cases:

• If the server returns {"error": "..."}, the SDK now treats that as the primary human-readable message (instead of falling back to a generic status-code message).
• If the server returns errorDetail, PdfRestApiError.response_content now contains the structured errorDetail object (including issues) so callers can inspect field-level failures directly.
• Non-JSON or otherwise unparseable error bodies still fall back to raw text behavior.

Breaking change callout: there is no method-signature break, but there is an observable error-handling behavior change. Code that assumed response_content was always str | None may need to handle dict when structured details are present, and code relying on previous raw-body behavior for {"error": ...} responses may need adjustment.

Validation

Validation was done with focused unit coverage and local execution:

• Added sync and async tests to ensure structured errorDetail is preserved on raised PdfRestApiError and exposes expected issue paths.
• Ran: uv run pytest tests/test_client.py -n auto --maxschedchunk 2 -k structured_error_detail (2 passed).

Limitations: full suite/matrix (uv run pytest and uvx nox -s tests) was not run as part of this focused verification.

Risks and follow-ups

Primary risk is integration compatibility around exception payload handling, especially in downstream code that pattern-matches response_content or stringifies exceptions for control flow.

Migration note: treat PdfRestApiError.response_content as dict | str | None; use the exception message for user-facing text and response_content["issues"] (when present) for programmatic diagnostics.

Rollout/monitoring: watch for consumer-side type assumptions in error handlers and for support reports tied to changed exception formatting. Follow-up candidates are adding a short README note with an error-handling example and expanding integration tests for real server errorDetail responses.

[netlify]

✅ Deploy Preview for pdfrest-python ready!

Name	Link
🔨 Latest commit	1ebf363
🔍 Latest deploy log	https://app.netlify.com/projects/pdfrest-python/deploys/69bc2b2d5bdb1800081d4a92
😎 Deploy Preview	https://deploy-preview-40--pdfrest-python.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[datalogics-cgreen]

These changes are not required: the test failures I saw were solely due to a separate reason. Testing with main against the repaired pdfRest build yielded no issue with accommodating the new error details.