[integrations][openai] Let provider exceptions reach the caller unwrapped

[weiqingy]

Linked issue: #936

Purpose of change

Case 3 of #936. The three OpenAI-family connections caught every exception from a chat call and rethrew it as a generic RuntimeException, while the Python connections let the SDK exception propagate unchanged. A caller writing against both languages saw different failure types for the same provider condition.

The SDK exceptions already carry the HTTP status and the provider's error payload, so the wrapper only forced callers to inspect a cause. This removes it from OpenAICompletionsConnection, AzureOpenAIChatModelConnection and OpenAIResponsesModelConnection, which aligns Java with Python. Local validation failures continue to raise IllegalArgumentException.

There is a second effect worth calling out. Each try also covered request building, so a local validation failure was rewrapped too. A tool message missing its externalId reached the caller as RuntimeException("Failed to call OpenAI chat completions API.") rather than as the IllegalArgumentException that OpenAIChatCompletionsUtils actually threw. Azure already had a catch (IllegalArgumentException e) { throw e; } guarding against exactly this, which is now unnecessary and is removed with the rest.

Out of scope: the wrappers around tool schema and tool argument JSON handling stay. Those wrap a checked JsonProcessingException from local work rather than a provider error, so they cannot propagate unwrapped.

Tests

OpenAICompletionsConnectionTest.testRequestBuildingFailurePropagatesUnwrapped and the same test in a new OpenAIResponsesModelConnectionTest call chat with a tool message that has no externalId and assert the IllegalArgumentException reaches the caller with its own type and message. Request building throws before the client is touched, so neither test needs a live API call.

I verified both tests discriminate rather than pass by construction: restoring the old catch block fails testRequestBuildingFailurePropagatesUnwrapped on the assertion, since the wrapper produces a plain RuntimeException that is not an IllegalArgumentException.

Azure gets no new test. Its IllegalArgumentException already propagated, so the only behavior that changed there is what happens to a provider SDK exception, and reaching that needs a live call through the final OpenAIClient.

mvn -pl integrations/chat-models/openai test passes, 72 tests. Spotless and RAT are clean.

API

No public API change. chat keeps its signature; only the exception type a caller observes on failure changes, from RuntimeException wrapping the SDK exception to the SDK exception itself.

Documentation

• doc-needed
• doc-not-needed
• doc-included

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

Generated-by: Claude Code 2.1.226

[wenjin272]

The new tests only exercise a request-building IllegalArgumentException, not the provider/SDK exception propagation that is the main contract of this PR. They guard against restoring the exact broad catch blocks, but would still pass if a future change caught and wrapped only OpenAI SDK exceptions. The Azure path has no new regression coverage at all, and its IllegalArgumentException already propagated before this PR, so the current suite cannot distinguish its provider-error behavior. Could we use a local fake HTTP endpoint returning a 4xx for Chat Completions, Responses, and Azure, then assert the concrete SDK exception type plus its status/error payload? That would verify the behavior at the level where the issue occurs and cover all three changed paths.

[weiqingy]

@wenjin272 Thanks for review.

You were right, and it wasn't hypothetical. I wrapped only com.openai.errors.OpenAIException around the SDK call in OpenAICompletionsConnection, and the whole existing suite still passed.

Added FakeOpenAIErrorEndpoint, a small local HTTP server that returns a 400 with an OpenAI error body, and one testProviderErrorPropagatesUnwrapped in each of the three connection test classes. Each asserts BadRequestException and the code from the payload. No new dependency, nothing under src/main. 72 tests to 75. That same wrapper now fails exactly those three tests and nothing else, Azure included.

Two caveats:

• Asserting statusCode() proves nothing on its own, since BadRequestException always returns 400. That line passes as soon as the type matches. The real check is the payload: change what the fake sends back and all three tests fail.
• I only cover 400, not 4xx generally. A 429 or a 5xx gets retried, so it costs three requests instead of one. 400 keeps the test quick.

The two testRequestBuildingFailurePropagatesUnwrapped tests stay. Wrapping only buildRequest(...) fails those two and not the new ones, so they catch different bugs.