Fix: OpenAI: map exceptions for streaming and moderation models (langchain4j#2986)

dliubarskyi · web-flow · commit c78a65de6c96 · 2025-05-12T17:04:30.000+02:00
## Issue `OpenAiStreamingChatModel`, `OpenAiStreamingLanguageModel` and `OpenAiModerationModel` are not mapping low-level `HttpException` to common exceptions (e.g., `AuthenticationException` and `RateLimitException`) like all other `OpenAi*Model` do. ## Change Map exceptions for `OpenAiStreamingChatModel`, `OpenAiStreamingLanguageModel` and `OpenAiModerationModel` ## General checklist - [ ] There are no breaking changes - [x] I have added unit and/or integration tests for my change - [x] The tests cover both positive and negative cases - [X] I have manually run all the unit and integration tests in the module I have added/changed, and they are all green - [X] I have manually run all the unit and integration tests in the [core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core) and [main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j) modules, and they are all green - [ ] I have added/updated the [documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs) - [ ] I have added an example in the [examples repo](https://github.com/langchain4j/langchain4j-examples) (only for "big" features) - [ ] I have added/updated [Spring Boot starter(s)](https://github.com/langchain4j/langchain4j-spring) (if applicable)
diff --git a/langchain4j-core/src/main/java/dev/langchain4j/internal/ExceptionMapper.java b/langchain4j-core/src/main/java/dev/langchain4j/internal/ExceptionMapper.java
@@ -32,13 +32,13 @@ default <T> T withExceptionMapper(Callable<T> action) {
         }
     }
 
-    RuntimeException mapException(Exception e);
+    RuntimeException mapException(Throwable t);
 
     class DefaultExceptionMapper implements ExceptionMapper {
 
         @Override
-        public RuntimeException mapException(Exception e) {
-            Throwable rootCause = findRoot(e);
+        public RuntimeException mapException(Throwable t) {
+            Throwable rootCause = findRoot(t);
 
             if (rootCause instanceof HttpException httpException) {
                 return mapHttpStatusCode(httpException, httpException.statusCode());
@@ -48,29 +48,29 @@ public RuntimeException mapException(Exception e) {
                 return new UnresolvedModelServerException(rootCause);
             }
 
-            return e instanceof RuntimeException re ? re : new LangChain4jException(e);
+            return t instanceof RuntimeException re ? re : new LangChain4jException(t);
         }
 
-        protected RuntimeException mapHttpStatusCode(Exception rootException, int httpStatusCode) {
+        protected RuntimeException mapHttpStatusCode(Throwable cause, int httpStatusCode) {
             if (httpStatusCode >= 500 && httpStatusCode < 600) {
-                return new InternalServerException(rootException);
+                return new InternalServerException(cause);
             }
             if (httpStatusCode == 401 || httpStatusCode == 403) {
-                return new AuthenticationException(rootException);
+                return new AuthenticationException(cause);
             }
             if (httpStatusCode == 404) {
-                return new ModelNotFoundException(rootException);
+                return new ModelNotFoundException(cause);
             }
             if (httpStatusCode == 408) {
-                return new TimeoutException(rootException);
+                return new TimeoutException(cause);
             }
             if (httpStatusCode == 429) {
-                return new RateLimitException(rootException);
+                return new RateLimitException(cause);
             }
             if (httpStatusCode >= 400 && httpStatusCode < 500) {
-                return new InvalidRequestException(rootException);
+                return new InvalidRequestException(cause);
             }
-            return rootException instanceof RuntimeException re ? re : new LangChain4jException(rootException);
+            return cause instanceof RuntimeException re ? re : new LangChain4jException(cause);
         }
 
         private static Throwable findRoot(Throwable e) {
diff --git a/langchain4j-jlama/src/main/java/dev/langchain4j/model/jlama/JlamaExceptionMapper.java b/langchain4j-jlama/src/main/java/dev/langchain4j/model/jlama/JlamaExceptionMapper.java
@@ -14,16 +14,16 @@ class JlamaExceptionMapper extends ExceptionMapper.DefaultExceptionMapper {
     private JlamaExceptionMapper() { }
 
     @Override
-    public RuntimeException mapException(final Exception e) {
-        if (e instanceof IOException && e.getMessage().startsWith(JLAMA_IOEXCEPTION_START_MESSAGE)) {
-            String httpStatusCode = e.getMessage().substring(JLAMA_IOEXCEPTION_START_MESSAGE.length(), JLAMA_IOEXCEPTION_START_MESSAGE.length() + 3);
+    public RuntimeException mapException(Throwable t) {
+        if (t instanceof IOException && t.getMessage().startsWith(JLAMA_IOEXCEPTION_START_MESSAGE)) {
+            String httpStatusCode = t.getMessage().substring(JLAMA_IOEXCEPTION_START_MESSAGE.length(), JLAMA_IOEXCEPTION_START_MESSAGE.length() + 3);
             try {
-                return mapHttpStatusCode(e, Integer.parseInt(httpStatusCode));
+                return mapHttpStatusCode(t, Integer.parseInt(httpStatusCode));
             } catch (NumberFormatException nfe) {
                 // ignore
             }
         }
 
-        return new InternalServerException(e);
+        return new InternalServerException(t);
     }
 }
diff --git a/langchain4j-open-ai/src/main/java/dev/langchain4j/model/openai/OpenAiModerationModel.java b/langchain4j-open-ai/src/main/java/dev/langchain4j/model/openai/OpenAiModerationModel.java
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import static dev.langchain4j.internal.RetryUtils.withRetry;
+import static dev.langchain4j.internal.RetryUtils.withRetryMappingExceptions;
 import static dev.langchain4j.internal.Utils.getOrDefault;
 import static dev.langchain4j.model.openai.internal.OpenAiUtils.DEFAULT_OPENAI_URL;
 import static dev.langchain4j.model.openai.internal.OpenAiUtils.DEFAULT_USER_AGENT;
@@ -71,7 +72,7 @@ private Response<Moderation> moderateInternal(List<String> inputs) {
                 .input(inputs)
                 .build();
 
-        ModerationResponse response = withRetry(() -> client.moderation(request).execute(), maxRetries);
+        ModerationResponse response = withRetryMappingExceptions(() -> client.moderation(request).execute(), maxRetries);
 
         int i = 0;
         for (ModerationResult moderationResult : response.results()) {
diff --git a/langchain4j-open-ai/src/main/java/dev/langchain4j/model/openai/OpenAiStreamingChatModel.java b/langchain4j-open-ai/src/main/java/dev/langchain4j/model/openai/OpenAiStreamingChatModel.java
@@ -1,6 +1,7 @@
 package dev.langchain4j.model.openai;
 
 import dev.langchain4j.http.client.HttpClientBuilder;
+import dev.langchain4j.internal.ExceptionMapper;
 import dev.langchain4j.model.ModelProvider;
 import dev.langchain4j.model.StreamingResponseHandler;
 import dev.langchain4j.model.chat.StreamingChatModel;
@@ -136,7 +137,9 @@ public void doChat(ChatRequest chatRequest, StreamingChatResponseHandler handler
                     ChatResponse chatResponse = openAiResponseBuilder.build();
                     handler.onCompleteResponse(chatResponse);
                 })
-                .onError(handler::onError)
+                .onError(throwable -> {
+                    handler.onError(ExceptionMapper.DEFAULT.mapException(throwable));
+                })
                 .execute();
     }
 
diff --git a/langchain4j-open-ai/src/main/java/dev/langchain4j/model/openai/OpenAiStreamingLanguageModel.java b/langchain4j-open-ai/src/main/java/dev/langchain4j/model/openai/OpenAiStreamingLanguageModel.java
@@ -1,6 +1,7 @@
 package dev.langchain4j.model.openai;
 
 import dev.langchain4j.http.client.HttpClientBuilder;
+import dev.langchain4j.internal.ExceptionMapper;
 import dev.langchain4j.model.StreamingResponseHandler;
 import dev.langchain4j.model.chat.response.ChatResponse;
 import dev.langchain4j.model.language.StreamingLanguageModel;
@@ -88,7 +89,9 @@ public void generate(String prompt, StreamingResponseHandler<String> handler) {
                             chatResponse.metadata().finishReason()
                     ));
                 })
-                .onError(handler::onError)
+                .onError(throwable -> {
+                    handler.onError(ExceptionMapper.DEFAULT.mapException(throwable));
+                })
                 .execute();
     }
 
diff --git a/langchain4j-open-ai/src/test/java/dev/langchain4j/model/openai/OpenAiChatModelErrorsTest.java b/langchain4j-open-ai/src/test/java/dev/langchain4j/model/openai/OpenAiChatModelErrorsTest.java
@@ -27,7 +27,7 @@ class OpenAiChatModelErrorsTest {
 
     private static final MockOpenai MOCK = new MockOpenai();
 
-    public static final Duration TIMEOUT = Duration.ofMillis(200);
+    public static final Duration TIMEOUT = Duration.ofMillis(300);
 
     ChatModel model = OpenAiChatModel.builder()
             .baseUrl(MOCK.baseUrl())
diff --git a/langchain4j-open-ai/src/test/java/dev/langchain4j/model/openai/OpenAiStreamingChatModelErrorsTest.java b/langchain4j-open-ai/src/test/java/dev/langchain4j/model/openai/OpenAiStreamingChatModelErrorsTest.java
@@ -0,0 +1,131 @@
+package dev.langchain4j.model.openai;
+
+import dev.langchain4j.exception.AuthenticationException;
+import dev.langchain4j.exception.HttpException;
+import dev.langchain4j.exception.InternalServerException;
+import dev.langchain4j.exception.InvalidRequestException;
+import dev.langchain4j.exception.LangChain4jException;
+import dev.langchain4j.exception.ModelNotFoundException;
+import dev.langchain4j.exception.RateLimitException;
+import dev.langchain4j.exception.TimeoutException;
+import dev.langchain4j.model.chat.StreamingChatModel;
+import dev.langchain4j.model.chat.response.ChatResponse;
+import dev.langchain4j.model.chat.response.StreamingChatResponseHandler;
+import io.ktor.http.HttpStatusCode;
+import me.kpavlov.aimocks.openai.MockOpenai;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import java.net.http.HttpTimeoutException;
+import java.time.Duration;
+import java.util.concurrent.CompletableFuture;
+import java.util.stream.Stream;
+
+import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;
+import static java.util.concurrent.TimeUnit.SECONDS;
+import static org.assertj.core.api.Assertions.assertThat;
+
+class OpenAiStreamingChatModelErrorsTest {
+
+    private static final MockOpenai MOCK = new MockOpenai();
+
+    public static final Duration TIMEOUT = Duration.ofMillis(300);
+
+    StreamingChatModel model = OpenAiStreamingChatModel.builder()
+            .baseUrl(MOCK.baseUrl())
+            .modelName(GPT_4_O_MINI)
+            .timeout(TIMEOUT)
+            .logRequests(true)
+            .logResponses(true)
+            .build();
+
+    public static Stream<Arguments> errors() {
+        return Stream.of(
+                Arguments.of(400, InvalidRequestException.class),
+                Arguments.of(401, AuthenticationException.class),
+                Arguments.of(403, AuthenticationException.class),
+                Arguments.of(404, ModelNotFoundException.class),
+                Arguments.of(413, InvalidRequestException.class),
+                Arguments.of(429, RateLimitException.class),
+                Arguments.of(500, InternalServerException.class),
+                Arguments.of(503, InternalServerException.class));
+    }
+
+    @ParameterizedTest
+    @MethodSource("errors")
+    void should_handle_error_responses(int httpStatusCode, Class<LangChain4jException> exception) throws Exception {
+
+        // given
+        final var question = "Return error: " + httpStatusCode;
+        MOCK.completion(req -> req.userMessageContains(question)).respondsError(res -> {
+            res.setHttpStatus(HttpStatusCode.Companion.fromValue(httpStatusCode));
+            res.setBody("");
+        });
+
+        CompletableFuture<Throwable> futureError = new CompletableFuture<>();
+        StreamingChatResponseHandler handler = new ErrorHandler(futureError);
+
+        // when
+        model.chat(question, handler);
+
+        // then
+        Throwable error = futureError.get(30, SECONDS);
+
+        assertThat(error)
+                .isExactlyInstanceOf(exception)
+                .satisfies(ex -> assertThat(((HttpException) ex.getCause()).statusCode())
+                        .as("statusCode")
+                        .isEqualTo(httpStatusCode));
+    }
+
+    @Test
+    void should_handle_timeout() throws Exception {
+
+        // given
+        final var question = "Simulate timeout";
+        MOCK.completion(req -> req.userMessageContains(question)).respondsError(res -> {
+            res.delayMillis(TIMEOUT.plusMillis(100).toMillis());
+            res.setHttpStatus(HttpStatusCode.Companion.getNoContent());
+            res.setBody("");
+        });
+
+        CompletableFuture<Throwable> futureError = new CompletableFuture<>();
+        StreamingChatResponseHandler handler = new ErrorHandler(futureError);
+
+        // when
+        model.chat(question, handler);
+
+        // then
+        Throwable error = futureError.get(30, SECONDS);
+
+        assertThat(error)
+                .isExactlyInstanceOf(TimeoutException.class)
+                .hasRootCauseExactlyInstanceOf(HttpTimeoutException.class);
+    }
+
+    class ErrorHandler implements StreamingChatResponseHandler {
+
+        private final CompletableFuture<Throwable> futureError;
+
+        ErrorHandler(CompletableFuture<Throwable> futureError) {
+            this.futureError = futureError;
+        }
+
+        @Override
+        public void onPartialResponse(String partialResponse) {
+            futureError.completeExceptionally(new RuntimeException("onPartialResponse must not be called"));
+        }
+
+        @Override
+        public void onCompleteResponse(ChatResponse completeResponse) {
+            futureError.completeExceptionally(new RuntimeException("onCompleteResponse must not be called"));
+        }
+
+        @Override
+        public void onError(Throwable error) {
+            futureError.complete(error);
+        }
+    }
+}
diff --git a/langchain4j-open-ai/src/test/java/dev/langchain4j/model/openai/OpenAiStreamingChatModelListenerIT.java b/langchain4j-open-ai/src/test/java/dev/langchain4j/model/openai/OpenAiStreamingChatModelListenerIT.java
@@ -3,6 +3,7 @@
 import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;
 import static java.util.Collections.singletonList;
 
+import dev.langchain4j.exception.AuthenticationException;
 import dev.langchain4j.exception.HttpException;
 import dev.langchain4j.model.chat.StreamingChatModel;
 import dev.langchain4j.model.chat.common.AbstractStreamingChatModelListenerIT;
@@ -46,6 +47,6 @@ protected StreamingChatModel createFailingModel(ChatModelListener listener) {
 
     @Override
     protected Class<? extends Exception> expectedExceptionClass() {
-        return HttpException.class;
+        return AuthenticationException.class;
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -32,13 +32,13 @@ default <T> T withExceptionMapper(Callable<T> action) {`
`32`	`32`	`}`
`33`	`33`	`}`
`34`	`34`
`35`		`- RuntimeException mapException(Exception e);`
	`35`	`+ RuntimeException mapException(Throwable t);`
`36`	`36`
`37`	`37`	`class DefaultExceptionMapper implements ExceptionMapper {`
`38`	`38`
`39`	`39`	`@Override`
`40`		`- public RuntimeException mapException(Exception e) {`
`41`		`- Throwable rootCause = findRoot(e);`
	`40`	`+ public RuntimeException mapException(Throwable t) {`
	`41`	`+ Throwable rootCause = findRoot(t);`
`42`	`42`
`43`	`43`	`if (rootCause instanceof HttpException httpException) {`
`44`	`44`	`return mapHttpStatusCode(httpException, httpException.statusCode());`
`@@ -48,29 +48,29 @@ public RuntimeException mapException(Exception e) {`
`48`	`48`	`return new UnresolvedModelServerException(rootCause);`
`49`	`49`	`}`
`50`	`50`
`51`		`- return e instanceof RuntimeException re ? re : new LangChain4jException(e);`
	`51`	`+ return t instanceof RuntimeException re ? re : new LangChain4jException(t);`
`52`	`52`	`}`
`53`	`53`
`54`		`- protected RuntimeException mapHttpStatusCode(Exception rootException, int httpStatusCode) {`
	`54`	`+ protected RuntimeException mapHttpStatusCode(Throwable cause, int httpStatusCode) {`
`55`	`55`	`if (httpStatusCode >= 500 && httpStatusCode < 600) {`
`56`		`- return new InternalServerException(rootException);`
	`56`	`+ return new InternalServerException(cause);`
`57`	`57`	`}`
`58`	`58`	`if (httpStatusCode == 401 \|\| httpStatusCode == 403) {`
`59`		`- return new AuthenticationException(rootException);`
	`59`	`+ return new AuthenticationException(cause);`
`60`	`60`	`}`
`61`	`61`	`if (httpStatusCode == 404) {`
`62`		`- return new ModelNotFoundException(rootException);`
	`62`	`+ return new ModelNotFoundException(cause);`
`63`	`63`	`}`
`64`	`64`	`if (httpStatusCode == 408) {`
`65`		`- return new TimeoutException(rootException);`
	`65`	`+ return new TimeoutException(cause);`
`66`	`66`	`}`
`67`	`67`	`if (httpStatusCode == 429) {`
`68`		`- return new RateLimitException(rootException);`
	`68`	`+ return new RateLimitException(cause);`
`69`	`69`	`}`
`70`	`70`	`if (httpStatusCode >= 400 && httpStatusCode < 500) {`
`71`		`- return new InvalidRequestException(rootException);`
	`71`	`+ return new InvalidRequestException(cause);`
`72`	`72`	`}`
`73`		`- return rootException instanceof RuntimeException re ? re : new LangChain4jException(rootException);`
	`73`	`+ return cause instanceof RuntimeException re ? re : new LangChain4jException(cause);`
`74`	`74`	`}`
`75`	`75`
`76`	`76`	`private static Throwable findRoot(Throwable e) {`
Original file line number	Diff line number	Diff line change
`@@ -14,16 +14,16 @@ class JlamaExceptionMapper extends ExceptionMapper.DefaultExceptionMapper {`
`14`	`14`	`private JlamaExceptionMapper() { }`
`15`	`15`
`16`	`16`	`@Override`
`17`		`- public RuntimeException mapException(final Exception e) {`
`18`		`- if (e instanceof IOException && e.getMessage().startsWith(JLAMA_IOEXCEPTION_START_MESSAGE)) {`
`19`		`- String httpStatusCode = e.getMessage().substring(JLAMA_IOEXCEPTION_START_MESSAGE.length(), JLAMA_IOEXCEPTION_START_MESSAGE.length() + 3);`
	`17`	`+ public RuntimeException mapException(Throwable t) {`
	`18`	`+ if (t instanceof IOException && t.getMessage().startsWith(JLAMA_IOEXCEPTION_START_MESSAGE)) {`
	`19`	`+ String httpStatusCode = t.getMessage().substring(JLAMA_IOEXCEPTION_START_MESSAGE.length(), JLAMA_IOEXCEPTION_START_MESSAGE.length() + 3);`
`20`	`20`	`try {`
`21`		`- return mapHttpStatusCode(e, Integer.parseInt(httpStatusCode));`
	`21`	`+ return mapHttpStatusCode(t, Integer.parseInt(httpStatusCode));`
`22`	`22`	`} catch (NumberFormatException nfe) {`
`23`	`23`	`// ignore`
`24`	`24`	`}`
`25`	`25`	`}`
`26`	`26`
`27`		`- return new InternalServerException(e);`
	`27`	`+ return new InternalServerException(t);`
`28`	`28`	`}`
`29`	`29`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@`
`3`	`3`	`import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;`
`4`	`4`	`import static java.util.Collections.singletonList;`
`5`	`5`
	`6`	`+import dev.langchain4j.exception.AuthenticationException;`
`6`	`7`	`import dev.langchain4j.exception.HttpException;`
`7`	`8`	`import dev.langchain4j.model.chat.StreamingChatModel;`
`8`	`9`	`import dev.langchain4j.model.chat.common.AbstractStreamingChatModelListenerIT;`
`@@ -46,6 +47,6 @@ protected StreamingChatModel createFailingModel(ChatModelListener listener) {`
`46`	`47`
`47`	`48`	`@Override`
`48`	`49`	`protected Class<? extends Exception> expectedExceptionClass() {`
`49`		`- return HttpException.class;`
	`50`	`+ return AuthenticationException.class;`
`50`	`51`	`}`
`51`	`52`	`}`