feat: add retryable exception

Author: stainless-app[bot]

README.md

@@ -1184,6 +1184,8 @@ The SDK throws custom unchecked exception types:
 
 - [`OpenAIIoException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIIoException.kt): I/O networking errors.
 
+- [`OpenAIRetryableException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIRetryableException.kt): Generic error indicating a failure that could be retried by the client.
+
 - [`OpenAIInvalidDataException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIInvalidDataException.kt): Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.
 
 - [`OpenAIException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIException.kt): Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.

openai-java-core/src/main/kotlin/com/openai/core/http/RetryingHttpClient.kt

@@ -3,6 +3,7 @@ package com.openai.core.http
 import com.openai.core.RequestOptions
 import com.openai.core.checkRequired
 import com.openai.errors.OpenAIIoException
+import com.openai.errors.OpenAIRetryableException
 import java.io.IOException
 import java.time.Clock
 import java.time.Duration
@@ -176,9 +177,10 @@ private constructor(
     }
 
     private fun shouldRetry(throwable: Throwable): Boolean =
-        // Only retry IOException and OpenAIIoException, other exceptions are not intended to be
-        // retried.
-        throwable is IOException || throwable is OpenAIIoException
+        // Only retry known retryable exceptions, other exceptions are not intended to be retried.
+        throwable is IOException ||
+            throwable is OpenAIIoException ||
+            throwable is OpenAIRetryableException
 
     private fun getRetryBackoffDuration(retries: Int, response: HttpResponse?): Duration {
         // About the Retry-After header:

openai-java-core/src/main/kotlin/com/openai/errors/OpenAIRetryableException.kt

@@ -0,0 +1,14 @@
+package com.openai.errors
+
+/**
+ * Exception that indicates a transient error that can be retried.
+ *
+ * When this exception is thrown during an HTTP request, the SDK will automatically retry the
+ * request up to the maximum number of retries.
+ *
+ * @param message A descriptive error message
+ * @param cause The underlying cause of this exception, if any
+ */
+class OpenAIRetryableException
+@JvmOverloads
+constructor(message: String? = null, cause: Throwable? = null) : OpenAIException(message, cause)

openai-java-core/src/test/kotlin/com/openai/core/http/RetryingHttpClientTest.kt

@@ -6,6 +6,7 @@ import com.github.tomakehurst.wiremock.junit5.WireMockTest
 import com.github.tomakehurst.wiremock.stubbing.Scenario
 import com.openai.client.okhttp.OkHttpClient
 import com.openai.core.RequestOptions
+import com.openai.errors.OpenAIRetryableException
 import java.io.InputStream
 import java.time.Duration
 import java.util.concurrent.CompletableFuture
@@ -251,6 +252,82 @@ internal class RetryingHttpClientTest {
         assertNoResponseLeaks()
     }
 
+    @ParameterizedTest
+    @ValueSource(booleans = [false, true])
+    fun execute_withRetryableException(async: Boolean) {
+        stubFor(post(urlPathEqualTo("/something")).willReturn(ok()))
+
+        var callCount = 0
+        val failingHttpClient =
+            object : HttpClient {
+                override fun execute(
+                    request: HttpRequest,
+                    requestOptions: RequestOptions,
+                ): HttpResponse {
+                    callCount++
+                    if (callCount == 1) {
+                        throw OpenAIRetryableException("Simulated retryable failure")
+                    }
+                    return httpClient.execute(request, requestOptions)
+                }
+
+                override fun executeAsync(
+                    request: HttpRequest,
+                    requestOptions: RequestOptions,
+                ): CompletableFuture<HttpResponse> {
+                    callCount++
+                    if (callCount == 1) {
+                        val future = CompletableFuture<HttpResponse>()
+                        future.completeExceptionally(
+                            OpenAIRetryableException("Simulated retryable failure")
+                        )
+                        return future
+                    }
+                    return httpClient.executeAsync(request, requestOptions)
+                }
+
+                override fun close() = httpClient.close()
+            }
+
+        val retryingClient =
+            RetryingHttpClient.builder()
+                .httpClient(failingHttpClient)
+                .maxRetries(2)
+                .sleeper(
+                    object : RetryingHttpClient.Sleeper {
+
+                        override fun sleep(duration: Duration) {}
+
+                        override fun sleepAsync(duration: Duration): CompletableFuture<Void> =
+                            CompletableFuture.completedFuture(null)
+                    }
+                )
+                .build()
+
+        val response =
+            retryingClient.execute(
+                HttpRequest.builder()
+                    .method(HttpMethod.POST)
+                    .baseUrl(baseUrl)
+                    .addPathSegment("something")
+                    .build(),
+                async,
+            )
+
+        assertThat(response.statusCode()).isEqualTo(200)
+        verify(
+            1,
+            postRequestedFor(urlPathEqualTo("/something"))
+                .withHeader("x-stainless-retry-count", equalTo("1")),
+        )
+        verify(
+            0,
+            postRequestedFor(urlPathEqualTo("/something"))
+                .withHeader("x-stainless-retry-count", equalTo("0")),
+        )
+        assertNoResponseLeaks()
+    }
+
     private fun retryingHttpClientBuilder() =
         RetryingHttpClient.builder()
             .httpClient(httpClient)