feat: improve error messaging #258

SoulPancake · 2025-11-11T09:23:21Z

Description

SDK errors currently only expose the operation name (e.g., "check") rather than the API's actual error message. This makes debugging difficult when errors occur.

Changes
Added fields to FgaError:

apiErrorMessage - Parsed error message from API response body (null if unavailable)
operationName - Operation that failed (e.g., "check", "write")
Enhanced getError() parsing:

Sets apiErrorMessage when successfully parsed from response JSON
Sets operationName for all errors
Maintains existing fallback behavior (operation name) for empty/non-JSON responses
Preserves backward compatibility:

getMessage() behavior unchanged - returns parsed message or operation name as before
All existing tests pass without modification
New fields are nullable and additive only

What problem is being solved?

How is it being solved?

What changes are made to solve it?

References

Review Checklist

I have clicked on "allow edits by maintainers".
I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
The correct base branch is being used, if not main
I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

Release Notes

Bug Fixes
- Improved error reporting with automatic parsing of API response details, including error codes, operation names, and request identifiers for enhanced troubleshooting and diagnostics.
Tests
- Added comprehensive test suite covering error parsing, fallback behavior, and error metadata handling.

feat: parse error msg feat: update changelog Removed two feature entries from the unreleased section. feat: set operation name and err msg

coderabbitai · 2025-11-11T09:23:27Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

The PR enhances error handling in the SDK by introducing JSON parsing utilities to extract detailed error messages and codes from API response bodies. It enriches FgaError instances with API metadata (apiErrorMessage, apiErrorCode, operationName) and includes comprehensive test coverage for various error scenarios and fallback behaviors.

Changes

Cohort / File(s)	Summary
Changelog Entry `CHANGELOG.md`	Adds unreleased changelog entry describing improved error messaging through parsing error details from response bodies for issue `#256`.
Error Handling Enhancement `src/main/java/dev/openfga/sdk/errors/FgaError.java`	Introduces `parseErrorMessage` and `extractErrorCode` JSON parsing utilities; adds centralized `ERROR_MAPPER` (ObjectMapper); extends FgaError with new fields (`apiErrorMessage`, `operationName`) and metadata getters/setters; enriches error construction with request ID, API error code, operation name, and retry-after header propagation; adds `getCode()` alias method.
Error Handling Tests `src/test/java/dev/openfga/sdk/errors/FgaErrorTest.java`	Introduces comprehensive test suite covering error parsing for validation, internal, and not-found errors; tests fallback behavior for missing/invalid response bodies; validates request ID and metadata extraction; tests authentication and rate-limiting error mappings; includes helper methods for mocking HttpResponse objects.

Sequence Diagram

sequenceDiagram
    participant Client
    participant SDK as SDK<br/>(getError)
    participant Parser as JSON Parser<br/>(ERROR_MAPPER)
    participant Error as FgaError
    
    Client->>SDK: HTTP Response + Request metadata
    SDK->>SDK: Determine error type<br/>(status code)
    SDK->>Parser: Parse response body
    alt Parsing succeeds
        Parser-->>SDK: errorMessage, errorCode
    else Parsing fails
        Parser-->>SDK: defaults (empty/null)
    end
    SDK->>Error: Create error instance<br/>(type, errorMessage)
    SDK->>Error: Enrich with metadata<br/>(operationName, apiErrorCode,<br/>requestId, retryAfter)
    Error-->>Client: Return populated<br/>FgaError

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

JSON parsing logic: Review parseErrorMessage and extractErrorCode for proper null-safety, exception handling, and edge cases with malformed or missing response bodies.
Metadata enrichment in getError(): Verify that all fields are correctly populated from response and headers, and that the operation-name fallback logic works as intended.
Test coverage: Confirm that the test suite adequately covers parsing failures, missing data scenarios, and correct metadata propagation across different error types.
Backward compatibility: Ensure the updated getError signature change does not break existing callers, particularly regarding the addition of Configuration and HttpResponse<String> parameters.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.26% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: improve error messaging' directly aligns with the main change: enhancing SDK error reporting by improving how error messages are parsed and presented from API responses.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov-commenter · 2025-11-11T09:27:39Z

Codecov Report

❌ Patch coverage is 82.48175% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.46%. Comparing base (d93032f) to head (bf18849).

Files with missing lines	Patch %	Lines
.../dev/openfga/sdk/errors/FgaApiValidationError.java	77.77%	4 Missing and 8 partials ⚠️
src/main/java/dev/openfga/sdk/errors/FgaError.java	85.54%	2 Missing and 10 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #258      +/-   ##
============================================
+ Coverage     36.47%   37.46%   +0.99%     
- Complexity     1144     1196      +52     
============================================
  Files           188      188              
  Lines          7192     7322     +130     
  Branches        824      854      +30     
============================================
+ Hits           2623     2743     +120     
+ Misses         4462     4456       -6     
- Partials        107      123      +16

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull Request Overview

This PR improves error messaging in the SDK by parsing actual API error messages from response bodies instead of only exposing operation names. It adds two new fields (apiErrorMessage and operationName) to the FgaError class while maintaining backward compatibility.

Extracts error messages and codes from JSON response bodies
Adds comprehensive test coverage for error parsing scenarios
Maintains fallback behavior to operation name when parsing fails

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
`src/main/java/dev/openfga/sdk/errors/FgaError.java`	Adds JSON parsing methods to extract error messages and codes from API responses, introduces new fields `apiErrorMessage` and `operationName` with getters/setters
`src/test/java/dev/openfga/sdk/errors/FgaErrorTest.java`	New comprehensive test suite covering various error scenarios including validation errors, internal errors, fallback cases, and edge cases with empty/non-JSON bodies
`CHANGELOG.md`	Documents the feature addition in the unreleased section

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/main/java/dev/openfga/sdk/errors/FgaError.java

CHANGELOG.md

src/main/java/dev/openfga/sdk/errors/FgaError.java

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/main/java/dev/openfga/sdk/errors/FgaApiValidationError.java

CHANGELOG.md

src/main/java/dev/openfga/sdk/errors/FgaApiValidationError.java

src/main/java/dev/openfga/sdk/errors/FgaError.java

src/main/java/dev/openfga/sdk/errors/FgaApiValidationError.java

SoulPancake · 2025-11-11T13:51:16Z

src/test/java/dev/openfga/sdk/api/auth/OAuth2ClientTest.java

                .get());

-        assertEquals("dev.openfga.sdk.errors.FgaApiRateLimitExceededError: exchangeToken", exception.getMessage());
+        // The error message now includes the formatted message from getMessage() override


This should be fine IMO

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/main/java/dev/openfga/sdk/errors/FgaApiValidationError.java

src/main/java/dev/openfga/sdk/errors/FgaError.java

src/test/java/dev/openfga/sdk/errors/FgaErrorIntegrationTest.java

src/main/java/dev/openfga/sdk/errors/FgaError.java

src/test-integration/java/dev/openfga/sdk/errors/FgaErrorIntegrationTest.java

SoulPancake added 2 commits November 11, 2025 14:51

feat: improve error messaging

2042e47

feat: parse error msg feat: update changelog Removed two feature entries from the unreleased section. feat: set operation name and err msg

feat: changelog update

acff828

fix: spotless fmt

b1912b2

SoulPancake marked this pull request as ready for review November 11, 2025 09:25

SoulPancake requested a review from a team as a code owner November 11, 2025 09:25

Copilot AI review requested due to automatic review settings November 11, 2025 09:25

Copilot started reviewing on behalf of SoulPancake November 11, 2025 09:25 View session

Copilot finished reviewing on behalf of SoulPancake November 11, 2025 09:27

Copilot AI reviewed Nov 11, 2025

View reviewed changes

src/main/java/dev/openfga/sdk/errors/FgaError.java Outdated Show resolved Hide resolved

src/main/java/dev/openfga/sdk/errors/FgaError.java Show resolved Hide resolved

CHANGELOG.md Outdated Show resolved Hide resolved

src/main/java/dev/openfga/sdk/errors/FgaError.java Show resolved Hide resolved

SoulPancake marked this pull request as draft November 11, 2025 10:08

set metadata and fix tests

7a2c8bd

SoulPancake marked this pull request as ready for review November 11, 2025 11:15

SoulPancake requested a review from Copilot November 11, 2025 11:15

Copilot started reviewing on behalf of SoulPancake November 11, 2025 11:16 View session

Copilot finished reviewing on behalf of SoulPancake November 11, 2025 11:18

Copilot AI reviewed Nov 11, 2025

View reviewed changes

SoulPancake added 2 commits November 11, 2025 17:17

feat: address copilot comments

b5cc8c1

fix: changelog update

56698c1

SoulPancake linked an issue Nov 11, 2025 that may be closed by this pull request

At Present the error messages does not contain any details. #84

Open

SoulPancake requested a review from Copilot November 11, 2025 13:47

Copilot started reviewing on behalf of SoulPancake November 11, 2025 13:48 View session

Copilot finished reviewing on behalf of SoulPancake November 11, 2025 13:50

SoulPancake commented Nov 11, 2025

View reviewed changes

Copilot AI reviewed Nov 11, 2025

View reviewed changes

SoulPancake added 2 commits November 11, 2025 19:44

feat: address copilot comments

768783c

Merge branch 'main' into feat/improve-err-msging-p1

d954ca6

ewanharris reviewed Nov 12, 2025

View reviewed changes

src/test/java/dev/openfga/sdk/errors/FgaErrorIntegrationTest.java Show resolved Hide resolved

src/main/java/dev/openfga/sdk/errors/FgaError.java Show resolved Hide resolved

feat: add integration tests

3987ace

SoulPancake added 2 commits November 12, 2025 19:38

feat: addres scomments reduce dupl

2f9f811

fix: spotless fmt

2e7c5b6

ewanharris reviewed Nov 12, 2025

View reviewed changes

src/test-integration/java/dev/openfga/sdk/errors/FgaErrorIntegrationTest.java Outdated Show resolved Hide resolved

feat: strict assertions

bf18849

SoulPancake requested a review from ewanharris November 12, 2025 19:39

feat: improve error messaging #258

Are you sure you want to change the base?

feat: improve error messaging #258

Conversation

SoulPancake commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What problem is being solved?

How is it being solved?

What changes are made to solve it?

References

Review Checklist

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai bot commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Other AI code review bot(s) detected

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Pre-merge checks and finishing touches

Uh oh!

codecov-commenter commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SoulPancake Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SoulPancake commented Nov 11, 2025 •

edited

Loading

coderabbitai bot commented Nov 11, 2025 •

edited

Loading

codecov-commenter commented Nov 11, 2025 •

edited

Loading