Skip to content

Conversation

newtork
Copy link
Contributor

@newtork newtork commented Aug 13, 2025

Context

Follow-up from #529

I've noticed multiple "nullable" accessors in our exceptions.
Users wouldn't really know what data is available at design-time.
We can harden the exceptions a little for stricter API contract.

Motivation:

Before

catch(OrchestrationClientException e) {
  ErrorResponse errSynchronous = e.getErrorResponse();
  ErrorResponseStreaming errStreaming = e.getErrorResponseStreaming()
}

After

catch(OrchestrationClientException.Streaming e) {
  ErrorResponseStreaming err = e.getErrorResponse();
}

Classes refactored:

  ClientException
    OrchestrationClientException
-     OrchestrationFilterException
-       Input
-       Output
+     Synchronous
+       InputFilter
+       OutputFilter
+     Streaming
+       InputFilter
+       OutputFilter

Feature scope:

  • OrchestrationFilterException
extends ClientException
{
  @Nullable String getMessage();  // default
  @Nullable Throwable getCause();  // default
  @Nullable ClassicHttpRequest getHttpRequest();
  @Nullable ClassicHttpResponse getHttpResponse();

- @Nullable ClientError getClientError();
+ @Nullable OrchestrationError getClientError();

- @Nullable Integer getStatusCode();
- @Nullable ErrorResponse getErrorResponse();
- @Nullable ErrorResponseStreaming getErrorResponseStreaming()
}
  • OrchestrationClientException.Synchronous
extends OrchestrationFilterException
{
+   @Nullable OrchestrationError.Synchronous getClientError();
+   @Nullable ErrorResponse getErrorResponse(); // model
}
  • OrchestrationClientException.Streaming
extends OrchestrationFilterException
{
+   @Nullable OrchestrationError.Streaming getClientError();
+   @Nullable ErrorResponseStreaming getErrorResponse(); // model
}
  • OrchestrationClientException.[Synchronous|Streaming].InputFilter
extends OrchestrationClientException.[Synchronous|Streaming] 
{
  @Nonnull Map<String, Object> getFilterDetails();
  @Nullable AzureContentSafetyInput getAzureContentSafetyInput();
  @Nullable LlamaGuard38b getLlamaGuard38b();
+ @Nullable Integer getStatusCode();
}
  • OrchestrationClientException.[Synchronous|Streaming].OutputFilter
extends OrchestrationClientException.[Synchronous|Streaming]
{
  @Nonnull Map<String, Object> getFilterDetails();
  @Nullable AzureContentSafetyOutput getAzureContentSafetyOutput();
  @Nullable LlamaGuard38b getLlamaGuard38b();
}

Split classes

  • OrchestrationFilterException.Output
    • OrchestrationClientException.Synchronous.OutputFilter
    • OrchestrationClientException.Streaming.OutputFilter
  • OrchestrationFilterException.Input
    • OrchestrationClientException.Synchronous.InputFilter
    • OrchestrationClientException.Streaming.InputFilter

Definition of Done

  • Functionality scope stated & covered
  • Tests cover the scope above
  • Error handling created / updated & covered by the tests above
  • Aligned changes with the JavaScript SDK
  • Documentation updated
  • Release notes updated

newtork and others added 26 commits August 6, 2025 11:38
…esponse

# Conflicts:
#	docs/release_notes.md
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationClientException.java
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationExceptionFactory.java
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationHttpExecutor.java
…esponse2

# Conflicts:
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationChatResponse.java
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationClient.java
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationClientException.java
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationFilterException.java
#	orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationHttpExecutor.java
Copy link
Member

@rpanackal rpanackal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surely, the approach removes the need for having an additional getErrorResponseStreaming()

Here are my concerns. Correct me if I wrong.

  1. Approach doesn't scale well if new exceptions are introduced apart from filtering .
  2. This would have been better solved (in terms of #lines added) with the OpenRewrite recipe to add a parent interface for ErrorResponse and ErrorResponseSreaming classes.

Overall, though the solution is valid, I feel more comfortable with having additional getErrorResponseStreaming.

The usage below, though not obvious, isn't unexpected.

 try {
   client.chatCompletion();
 } catch (OrchestrationCLientException e) {
   e.getErrorResponse();
 }
  try {
   client.streamChatCompletion();
 } catch (OrchestrationCLientException e) {
   e.getErrorResponseStreaming();
 }

We could also go about with adding documentation and improved javadoc for clarity.

@newtork newtork added the please-review Request to review a pull-request label Aug 15, 2025
@newtork newtork marked this pull request as draft August 15, 2025 10:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
please-review Request to review a pull-request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants