[ZedingZhang (ZedingZhang)]

Motivation & Context

Flat Responses API SSE error events currently become text-only RuntimeError instances before being wrapped in ChatClientException. Applications lose the provider's structured error code, message, and parameter when they unwrap the exception, preventing reliable error classification for bounded retries and telemetry.

Description & Review Guide

• What are the major changes? Retain the original ResponseErrorEvent and its code, message, and param on a private RuntimeError subclass used by the existing error wrapper. Add regression coverage for normal streaming, structured-output streaming, and resumed streaming, including server_error, rate_limit_exceeded, absent codes, and populated or absent parameters.
• What is the impact of these changes? Callers can recover the structured provider details through ChatClientException.__cause__ without parsing exception text. The existing exception message and RuntimeError compatibility are preserved, as is continuation-token cleanup on a failed resumed stream. There are no new public exports or dependencies. The OpenAI package's unit tests, source and test typing checks, formatting, lint, package build, and commit hooks pass locally.
• What do you want reviewers to focus on? Confirm that the private error carrier exposes the appropriate provider metadata while preserving the existing exception wrapping and message. The regression exercises each request path and asserts that no error event is emitted as a normal response update.

The advisory Public API Compatibility check currently crashes with Griffe 2.4.0 while resolving the unchanged base-side agent_framework._workflows._edge.EdgeGroup.builtin_type alias to builtins.type. Comparing the unmodified base commit a8e284ca8ce7c2a6b4a4641ef35e131d75a5cda3 with itself reproduces the same AliasResolutionError; the check does not reach this package's comparison. Other substantive fork workflows are awaiting maintainer approval.

Related Issue

Fixes #9593

The issue is currently marked reproduced, without a ready-for-implementation label or an explicit maintainer approval comment. This PR presents the focused reproduction and fix for maintainer confirmation. No competing open PR referencing this issue was found at submission.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Codex assisted with issue analysis, implementation, regression tests, and this PR description. The reported regression was reproduced locally, and the final change received separate standards and specification reviews.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟢 Approval recommended

The focused change preserves existing exception behavior and covers the affected streaming paths, with no blocking issues identified.

No open issues 🎉

What changed in this PR

Preserves structured metadata from OpenAI Responses SSE error events, addressing #9593 so callers can classify provider errors without parsing exception text.

Changes:

• Adds a private RuntimeError subclass retaining the original event and its code, message, and param, while preserving existing error text and wrapping.
• Adds regression coverage for normal, structured-output, and resumed streaming, including continuation-token cleanup and rejection of error events as response updates.

File	Description
python/​packages/​openai/​tests/​openai/​test_openai_chat_client.py	Tests metadata preservation across streaming paths and error variants.
python/​packages/​openai/​agent_framework_openai/​_chat_client.py	Retains provider error metadata in the existing exception chain.

_{Review effort: Balanced}