fix: handle pydantic ValidationError in beta.chat.completions.parse (fixes #1763)

[giulio-leone]

Problem

When beta.chat.completions.parse() receives malformed or truncated JSON from the API (with finish_reason: "stop"), a raw pydantic.ValidationError is raised directly to the user with no context about what went wrong or what the original content was.

This is confusing because:

• The error doesn't indicate it came from parsing the API response
• The raw content that failed to parse is lost
• Users can't distinguish between a bug in their code vs bad API output

Solution

Added a new ContentFormatError exception (extends OpenAIError, following the pattern of LengthFinishReasonError) that wraps both pydantic.ValidationError and json.JSONDecodeError in _parse_content().

The new error:

• Provides a clear message explaining the response didn't match the expected format
• Preserves the raw content string via raw_content attribute for debugging
• Chains the original exception as __cause__ so the full traceback is available

Changes

• src/openai/_exceptions.py: Added ContentFormatError class
• src/openai/__init__.py: Exported ContentFormatError
• src/openai/lib/_parsing/_completions.py: Wrapped _parse_content() with try/except
• tests/lib/chat/test_completions.py: Added tests for malformed JSON and schema mismatch

Example

try:
    completion = client.beta.chat.completions.parse(
        model="gpt-4o",
        messages=[...],
        response_format=MyModel,
    )
except openai.ContentFormatError as e:
    print(e.raw_content)  # The raw JSON string that failed to parse

Fixes #1763

[Copilot]

Pull request overview

Adds a dedicated SDK error for structured-output parsing failures so users get a clear, actionable exception (with access to the raw model content) instead of a bare pydantic.ValidationError when chat.completions.parse() receives malformed/truncated JSON.

Changes:

• Introduces ContentFormatError (subclass of OpenAIError) to represent response-format parsing failures.
• Wraps Pydantic parsing in _parse_content() to raise ContentFormatError on pydantic.ValidationError / json.JSONDecodeError.
• Adds regression tests covering malformed JSON and schema mismatch cases, and exports the new exception from openai.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
src/openai/lib/_parsing/_completions.py	Wraps response-format parsing to raise a consistent SDK exception instead of leaking raw Pydantic errors.
src/openai/_exceptions.py	Adds ContentFormatError carrying raw_content for debugging.
src/openai/__init__.py	Exports ContentFormatError from the top-level package.
tests/lib/chat/test_completions.py	Adds tests asserting ContentFormatError and raw_content preservation for malformed JSON and schema mismatch.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[giulio-leone]

Thanks for the thorough review! All feedback has been addressed in 81f3e5b:

• raw_content truncation: Error message now caps at 500 chars; full content still available via .raw_content
• Redundant __cause__: Removed; original exception stored on .error attribute instead
• Docstring accuracy: Updated to cover both Pydantic BaseModel and dataclass-like types
• response_format type in error: Kept as-is — the ValidationError/JSONDecodeError already identifies the expected schema, and the caller knows the type they passed