non-transaction write error handling

Author: jimmyjames

.openapi-generator/FILES

@@ -164,6 +164,8 @@ src/main/java/dev/openfga/sdk/api/client/model/ClientWriteAssertionsResponse.jav
 src/main/java/dev/openfga/sdk/api/client/model/ClientWriteAuthorizationModelResponse.java
 src/main/java/dev/openfga/sdk/api/client/model/ClientWriteRequest.java
 src/main/java/dev/openfga/sdk/api/client/model/ClientWriteResponse.java
+src/main/java/dev/openfga/sdk/api/client/model/ClientWriteSingleResponse.java
+src/main/java/dev/openfga/sdk/api/client/model/ClientWriteStatus.java
 src/main/java/dev/openfga/sdk/api/configuration/AdditionalHeadersSupplier.java
 src/main/java/dev/openfga/sdk/api/configuration/ApiToken.java
 src/main/java/dev/openfga/sdk/api/configuration/BaseConfiguration.java

CHANGELOG.md

@@ -2,30 +2,6 @@
 
 ## [Unreleased](https://github.com/openfga/java-sdk/compare/v0.8.3...HEAD)
 
-### Added
-- feat: RFC 9110 compliant Retry-After header support with exponential backoff and jitter
-- feat: Enhanced retry strategy with delay calculation
-- feat: Retry-After header value exposed in error objects for better observability
-- feat: Input validation for Configuration.minimumRetryDelay() to prevent negative values
-- feat: Default value (100ms) now explicitly set for minimumRetryDelay configuration
-
-### Changed
-- **BREAKING**: Maximum allowable retry count is now enforced at 15 (default remains 3)
-- **BREAKING**: FgaError now exposes Retry-After header value via getRetryAfterHeader() method
-- **BREAKING**: Configuration.minimumRetryDelay() now requires non-null values and validates input, throwing IllegalArgumentException for null or negative values
-
-### Technical Details
-- Implements RFC 9110 compliant Retry-After header parsing (supports both integer seconds and HTTP-date formats)
-- Adds exponential backoff with jitter (base delay: 2^retryCount * 100ms, capped at 120 seconds)
-- Validates Retry-After values between 1-1800 seconds (30 minutes maximum)
-- Prioritizes Retry-After header delays over exponential backoff when present
-- Unified retry behavior: All requests retry on 429s and 5xx errors (except 501 Not Implemented)
-
-**Migration Guide**: 
-- Update error handling code if using FgaError properties - new getRetryAfterHeader() method available
-- Note: Maximum allowable retries is now enforced at 15 (validation added to prevent exceeding this limit)
-- **IMPORTANT**: Configuration.minimumRetryDelay() now requires non-null values and validates input - ensure you're not passing null or negative Duration values, as this will now throw IllegalArgumentException. Previously null values were silently accepted and would fall back to default behavior at runtime.
-
 ## v0.8.3
 
 ### [0.8.3](https://github.com/openfga/java-sdk/compare/v0.8.2...v0.8.3) (2025-07-15)

README.md

@@ -125,7 +125,7 @@ libraryDependencies += "dev.openfga" % "openfga-sdk" % "0.8.3"
 
 We strongly recommend you initialize the `OpenFgaClient` only once and then re-use it throughout your app, otherwise you will incur the cost of having to re-initialize multiple times or at every request, the cost of reduced connection pooling and re-use, and would be particularly costly in the client credentials flow, as that flow will be preformed on every request.
 
-> The `Client` will by default retry API requests up to 3 times. Rate limiting (429) errors are always retried. Server errors (5xx) are retried for all operations, with delay calculation using `Retry-After` headers when provided or exponential backoff as fallback.
+> The `Client` will by default retry API requests up to 3 times on 429 and 5xx errors.
 
 #### No Credentials
 
@@ -714,7 +714,7 @@ response.getResult() = [{
 
 If you are using an OpenFGA version less than 1.8.0, you can use `clientBatchCheck`, 
 which calls `check` in parallel. It will return `allowed: false` if it encounters an error, and will return the error in the body.
-If 429s are encountered, the underlying check will retry up to 3 times. For 5xx errors, all requests will retry with delay calculation using `Retry-After` headers when provided or exponential backoff as fallback.
+If 429s or 5xxs are encountered, the underlying check will retry up to 3 times before giving up.
 
 ```
 var request = List.of(
@@ -965,28 +965,9 @@ fgaClient.writeAssertions(assertions, options).get();
 
 ### Retries
 
-The SDK implements RFC 9110 compliant retry behavior with support for the `Retry-After` header. By default, the SDK will automatically retry failed requests up to **3 times** with delay calculation (maximum allowable: 15 retries).
+If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 3 times with a minimum wait time of 100 milliseconds between each attempt.
 
-#### Retry Behavior
-
-**Rate Limiting (429 errors):** Always retried regardless of HTTP method.
-
-**Server Errors (5xx):** All requests are retried on 5xx errors (except 501 Not Implemented) regardless of HTTP method:
-- **All operations** (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS): Always retried on 5xx errors with delay calculation
-
-#### Delay Calculation
-
-1. **Retry-After header present**: Uses the server-specified delay (supports both integer seconds and HTTP-date formats)
-2. **No Retry-After header**: Uses exponential backoff with jitter (base delay: 2^retryCount * 100ms, capped at 120 seconds)
-3. **Minimum delay**: Respects the configured `minimumRetryDelay` as a floor value
-
-#### Configuration
-
-Customize retry behavior using the `ClientConfiguration` builder. The SDK enforces a maximum of 15 retries to prevent accidental server overload:
-
-**⚠️ Breaking Changes:**
-- Configuration validation now prevents setting `maxRetries` above 15
-- `FgaError` now exposes the `Retry-After` header value via `getRetryAfterHeader()`
+To customize this behavior, call `maxRetries` and `minimumRetryDelay` on the `ClientConfiguration` builder. `maxRetries` determines the maximum number of retries (up to 15), while `minimumRetryDelay` sets the minimum wait time between retries in milliseconds.
 
 ```java
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -1000,37 +981,15 @@ public class Example {
                 .apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "http://localhost:8080"
                 .storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores()
                 .authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request
-                .maxRetries(3) // retry up to 3 times on API requests (default: 3, maximum: 15)
-                .minimumRetryDelay(100); // minimum wait time between retries in milliseconds (default: 100ms)
+                .maxRetries(3) // retry up to 3 times on API requests
+                .minimumRetryDelay(250); // wait a minimum of 250 milliseconds between requests
 
         var fgaClient = new OpenFgaClient(config);
         var response = fgaClient.readAuthorizationModels().get();
     }
 }
 ```
 
-#### Error Handling with Retry Information
-
-When handling errors, you can access the `Retry-After` header value for debugging or custom retry logic:
-
-```java
-try {
-    var response = fgaClient.check(request).get();
-} catch (ExecutionException e) {
-    if (e.getCause() instanceof FgaError) {
-        FgaError error = (FgaError) e.getCause();
-        
-        // Access Retry-After header if present
-        String retryAfter = error.getRetryAfterHeader();
-        if (retryAfter != null) {
-            System.out.println("Server requested retry after: " + retryAfter + " seconds");
-        }
-        
-        System.out.println("Error: " + error.getMessage());
-    }
-}
-```
-
 ### API Endpoints
 
 | Method | HTTP request | Description |

build.gradle

@@ -4,7 +4,7 @@ plugins {
     // Quality
     id 'jacoco'
     id 'jvm-test-suite'
-    id 'com.diffplug.spotless' version '7.2.1'
+    id 'com.diffplug.spotless' version '7.0.4'
 
     // IDE
     id 'idea'
@@ -55,7 +55,7 @@ jacocoTestReport {
 }
 
 ext {
-    jackson_version = "2.19.2"
+    jackson_version = "2.19.1"
 }
 
 dependencies {
@@ -65,7 +65,7 @@ dependencies {
     implementation "com.fasterxml.jackson.core:jackson-databind:$jackson_version"
     implementation "com.fasterxml.jackson.datatype:jackson-datatype-jsr310:$jackson_version"
     implementation "org.openapitools:jackson-databind-nullable:0.2.6"
-    implementation platform("io.opentelemetry:opentelemetry-bom:1.52.0")
+    implementation platform("io.opentelemetry:opentelemetry-bom:1.51.0")
     implementation "io.opentelemetry:opentelemetry-api"
 }
 
@@ -76,7 +76,7 @@ testing {
             dependencies {
                 implementation 'org.assertj:assertj-core:3.27.3'
                 implementation 'org.mockito:mockito-core:5.18.0'
-                implementation 'org.junit.jupiter:junit-jupiter:5.13.4'
+                implementation 'org.junit.jupiter:junit-jupiter:5.13.2'
                 implementation 'org.wiremock:wiremock:3.13.1'
 
                 runtimeOnly 'org.junit.platform:junit-platform-launcher'

example/example1/build.gradle

@@ -1,6 +1,6 @@
 plugins {
     id 'application'
-    id 'com.diffplug.spotless' version '7.2.1'
+    id 'com.diffplug.spotless' version '7.0.4'
     id 'org.jetbrains.kotlin.jvm' version '2.2.0'
 }
 
@@ -19,7 +19,7 @@ repositories {
 }
 
 ext {
-    jacksonVersion = "2.19.2"
+    jacksonVersion = "2.19.1"
 }
 
 dependencies {

example/example1/src/main/java/dev/openfga/sdk/example/Example1.java

@@ -18,9 +18,9 @@ public void run(String apiUrl) throws Exception {
         if (System.getenv("FGA_CLIENT_ID") != null) {
             credentials = new Credentials(new ClientCredentials()
                     .apiAudience(System.getenv("FGA_API_AUDIENCE"))
-                    .apiTokenIssuer(System.getenv("FGA_TOKEN_ISSUER"))
-                    .clientId("FGA_CLIENT_ID")
-                    .clientSecret("FGA_CLIENT_SECRET"));
+                    .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
+                    .clientId(System.getenv("FGA_CLIENT_ID"))
+                    .clientSecret(System.getenv("FGA_CLIENT_SECRET")));
         } else {
             System.out.println("Proceeding with no credentials (expecting localhost)");
         }
@@ -102,10 +102,20 @@ public void run(String apiUrl) throws Exception {
         fgaClient
                 .write(
                         new ClientWriteRequest()
-                                .writes(List.of(new ClientTupleKey()
-                                        .user("user:anne")
-                                        .relation("writer")
-                                        ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"))),
+                                .writes(List.of(
+                                        new ClientTupleKey()
+                                                .user("user:anne")
+                                                .relation("writer")
+                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"),
+                                        new ClientTupleKey()
+                                                .user("user:anne")
+                                                .relation("writer")
+                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"), // duplicate
+                                        new ClientTupleKey()
+                                                .user("user:anne")
+                                                .relation("owner")
+                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a") // different relation
+                                )),
                         new ClientWriteOptions()
                                 .disableTransactions(true)
                                 .authorizationModelId(authorizationModel.getAuthorizationModelId()))

settings.gradle

@@ -1 +1,8 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+
 rootProject.name = 'openfga-sdk'