[Kayvan-Zahiri]

An HTTP 502 HTML/plain-text response currently raises JSONDecodeError from search() / async_search(), hiding the SDK error contract. JSON error responses without the expected object envelope can instead fall through into success-response parsing, or raise TypeError / AttributeError for null/scalar error values.

Catch JSON decoding failures and validate the error-envelope shape before accessing it. Unexpected bodies raise the existing UnknownError with the HTTP status and original response text. Valid structured errors continue through the existing status/code-specific mapping unchanged. The shared helper covers both sync and async requests, including their existing payment-retry path.

Added 18 public-client regression cases covering HTML, empty/plain-text bodies, JSON null/arrays, missing error envelopes, null/string error values, and a valid unknown-error control. Sixteen fail against the original implementation; two controls pass.

Validation (Python 3.13, locked development dependencies):

• Repository-prescribed make lint typecheck test passes, including the new tracked regression file in pre-commit checks.
• All 128 tests pass, with 96% total coverage.
• uv build creates the wheel and source distribution.
• Staged and working-tree git diff --check pass.

Responses are mocked at the HTTP request boundary. No live searches, account operations, or payment signing/settlement were performed. No package version or release configuration changes.