fix: preserve response headers on parsing and stream errors

[sylvesterkaczmarek]

This pull request preserves available HTTP response headers when response parsing or streaming fails, so callers can inspect diagnostics such as x-request-id.

Problem

OpenAIInvalidDataException and OpenAIIoException currently carry only a message and cause. This drops response metadata even in error paths where an HttpResponse already exists:

• JsonHandler wraps body read/deserialization failures as OpenAIInvalidDataException.
• StreamHandler wraps reader IOExceptions as OpenAIIoException.

That makes production debugging harder because callers cannot recover response headers such as x-request-id.

Changes

• add optional headers() accessors to OpenAIInvalidDataException and OpenAIIoException
• keep the existing two-parameter primary constructors unchanged
• use internal secondary constructors only when response headers are available
• attach response.headers() when JSON body parsing fails
• attach response headers when a streaming reader fails
• leave pre-response transport failures unchanged, where no response headers exist
• add focused regression coverage for both error paths

Compatibility

The original primary constructor signatures and Kotlin default-argument ABI remain unchanged, and the existing Java overloads are preserved. The new header metadata is additive and optional.

Validation

• verified the branch is based on upstream main at 95f4a1173c119ad08a049d752ec67de251434938
• verified the diff is limited to the two exception types, the JSON/stream handlers, and focused tests
• focused regression tests are included for x-request-id propagation
• full repository validation is left to GitHub Actions because this environment does not have a complete local checkout/toolchain

Fixes #690

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: df0e205eff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sylvesterkaczmarek]

I resolved this PR against current main while preserving the intended fix and newer upstream behavior. The branch is now mergeable and no longer has a base conflict. Could a maintainer please re-review it when convenient?

@codex review