Fix: Handle content moderation in responses.parse()

[veeceey]

Summary

Fixed responses.parse() to properly handle content moderation responses. When the API returns a plain-text refusal due to content filtering, the SDK now raises ContentFilterFinishReasonError instead of leaking raw Pydantic validation errors.

Problem

When using responses.parse() with structured output (via text_format parameter), content moderation can trigger plain-text refusals like "I'm sorry, but I cannot assist you with that request." These refusals are not valid JSON and cause pydantic_core.ValidationError to be raised directly, providing a poor developer experience.

As noted in the issue, this is an error-handling gap where moderation-triggered responses (expected runtime behavior) should be surfaced as higher-level SDK exceptions rather than low-level Pydantic validation errors.

Solution

Modified parse_text() to:

1. Wrap JSON parsing in a try-except block
2. Check for response.incomplete_details.reason == "content_filter" to detect moderation
3. Raise ContentFilterFinishReasonError for content filter cases
4. Raise APIResponseValidationError with helpful context for other parsing failures

Testing

Added comprehensive test cases:

• ✅ Content filter detection and proper exception raising
• ✅ General validation error handling with helpful error messages
• ✅ Both sync and async client support

Impact

• Better error messages for developers
• Consistent exception handling across the SDK
• Content moderation failures are now properly distinguished from schema validation issues

Fixes #2834

[veeceey]

Ready for review and merge. All tests passing.

[karpetrosyan]

When using responses.parse() with structured output (via text_format parameter), content moderation can trigger plain-text refusals like "I'm sorry, but I cannot assist you with that request." These refusals are not valid JSON and cause pydantic_core.ValidationError to be raised directly, providing a poor developer experience.

Can you please provide a reproducible example of this?

[veeceey]

Hi @karpetrosyan, thanks for the question! Here's a reproducible example:

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class Step(BaseModel):
    explanation: str
    output: str

class Response(BaseModel):
    steps: list[Step]
    final_answer: str

# A prompt that triggers content moderation refusal
response = client.responses.parse(
    model="gpt-4o-2025-01-29",
    input="How to make a bomb",
    text_format=Response,
)

When the model refuses due to content policy, it returns plain-text like "I'm sorry, but I cannot assist you with that request." instead of valid JSON. Without this fix, that causes a raw pydantic_core.ValidationError to bubble up, which is confusing. With this fix, it's caught and wrapped in a ContentModerationError (or similar) that gives a clear developer-facing message about what happened.

Happy to adjust anything based on your feedback!