feat(gax-httpjson): add HttpJsonErrorParser utility by westarle · Pull Request #4137 · googleapis/sdk-platform-java · GitHub

This PR introduces the HttpJsonErrorParser, a shared utility within gax-httpjson responsible for extracting and unpacking com.google.rpc.Status payloads embedded within HTTP JSON error responses.

Specifically, it uses JsonFormat and a custom TypeRegistry to cleanly unpack Any details (such as google.rpc.ErrorInfo) into a standard com.google.api.gax.rpc.ErrorDetails object. This achieves structural parity with how errors are extracted from gRPC trailers, doing so without consuming the underlying InputStream on the wire.

Context & Future Use

This utility is the first building block in a broader initiative to implement production logging across the Java client libraries. In upcoming PRs, this parser will be utilized directly by the HttpJsonLoggingInterceptor to safely unpack error metadata (like reason, domain, and metadata from ErrorInfo).

Testing

Added comprehensive unit tests in HttpJsonErrorParserTest.
Verified correct extraction of ErrorInfo details and handling of empty or malformed JSON payloads.

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new utility, HttpJsonErrorParser, designed to standardize and simplify the parsing of Google Cloud error responses received over HTTP/JSON. This enhancement allows the GAX framework to more effectively extract structured error details from JSON payloads, improving error handling capabilities for clients interacting with Google Cloud APIs.

Highlights

New Utility Added: Introduced HttpJsonErrorParser to parse Google Cloud error responses from JSON payloads into ErrorDetails objects.
Standardized Error Parsing: The parser is designed to extract structured error information from standard Google Cloud error JSON, which typically includes a top-level "error" object with a "details" list.
Comprehensive Testing: Added a dedicated test file, HttpJsonErrorParserTest, with various test cases to ensure the robust and correct functionality of the new error parser under different scenarios.

Changelog

gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonErrorParser.java
- Added HttpJsonErrorParser class to provide static methods for parsing Google Cloud error JSON into ErrorDetails.
- Implemented parseErrorDetails method to handle JSON structures containing a top-level "error" object with a "details" list.
- Integrated Gson and JsonFormat for JSON parsing and Protobuf merging.
gax-java/gax-httpjson/src/test/java/com/google/api/gax/httpjson/HttpJsonErrorParserTest.java
- Added HttpJsonErrorParserTest with test cases for successful parsing of ErrorInfo.
- Included tests for scenarios with no ErrorInfo, empty/null payloads, invalid JSON, and missing error objects/details.

Activity

No human activity has been recorded on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

Code Review

This pull request introduces a new HttpJsonErrorParser utility for parsing error details from JSON responses, along with corresponding unit tests. The implementation is sound, but I have one suggestion to improve both performance and correctness. The suggestion involves avoiding unnecessary object creation and ensuring the method's behavior aligns with the expectations set by the unit tests, specifically regarding the handling of payloads without error details.

It's better to use an empty ErrorDetails object to avoid null checks by the caller.

Makes sense! Done, and returned in case of problems reading the errorinfo too.

This is probably OK for now since we only need getErrorInfo(). But the ErrorDetails we are building is going to error out if we try to call getDebugInfo().

I pulled some more things into the registry, PTAL

Which method might throw InvalidProtocolBufferException?

I wrapped it more closely, thanks!

This and following catch block swallowed the exception, which I don't think is a best practice. It's better to re-throw them with a runtime exception and let the caller decide how to handle them.

I changed this to just return the empty object. I think it is expected that some results will have a field called "error" that has something else in it.

Is the format of the error specified somewhere? Could it be in fields other than "error"?

added a link to https://google.aip.dev/193#http11json-representation to the class

…HttpJsonErrorParser

…d of throwing RuntimeException

…s and localize catches

…name method to parseStatus

thanks for the detailed feedback, I think it looks much better.

I changed the return type to Status and made all the (expected for many APIs) failure paths return an empty status.

added a link to https://google.aip.dev/193#http11json-representation to the class

Makes sense! Done, and returned in case of problems reading the errorinfo too.

I pulled some more things into the registry, PTAL

I wrapped it more closely, thanks!

I changed this to just return the empty object. I think it is expected that some results will have a field called "error" that has something else in it.

LGTM, thanks!

🤖 I have created a release *beep* *boop* --- <details><summary>2.68.0</summary> ## [2.68.0](v2.67.0...v2.68.0) (2026-03-17) ### Features * Add client request duration metric. ([#4132](#4132)) ([6a76397](6a76397)) * Add more attributes to golden signals metrics. ([#4135](#4135)) ([59d0624](59d0624)) * **gax-httpjson:** add HttpJsonErrorParser utility ([#4137](#4137)) ([a1b7565](a1b7565)) * **generator:** add extra allowed modules that will not be removed from the monorepo if they are present ([#4124](#4124)) ([774fe6e](774fe6e)) * **o11y:** introduce `gcp.client.repo` and `gcp.client.artifact` attributes ([#4120](#4120)) ([105f644](105f644)) * **o11y:** Introduce `rpc.system.name` and `rpc.method` in gRPC ([#4121](#4121)) ([7ab6d2e](7ab6d2e)) * **o11y:** introduce server.port attribute ([#4128](#4128)) ([56aa343](56aa343)) ### Bug Fixes * add null checks for ApiTracerFactory in ClientContext ([#4122](#4122)) ([4b3dbe2](4b3dbe2)) * Decrease log level for directpath warnings outside GCE ([#4139](#4139)) ([c9651e7](c9651e7)) * **gax-grpc:** add pick_first fallback to direct path service config ([#4143](#4143)) ([b150fe9](b150fe9)) * Populate method level attributes in metrics recording ([#4149](#4149)) ([7b7e6c9](7b7e6c9)) * suppress warnings in generated projects for non-idiomatic durations ([#4119](#4119)) ([4206e6e](4206e6e)) * Use ServiceName + MethodName as the regex for Otel ([#2543](#2543)) ([b9ae73f](b9ae73f)) ### Documentation * **hermetic_build:** fix config field name in readme ([#4130](#4130)) ([a0c8f67](a0c8f67)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

🤖 I have created a release *beep* *boop* --- <details><summary>2.68.0</summary> ## [2.68.0](googleapis/sdk-platform-java@v2.67.0...v2.68.0) (2026-03-17) ### Features * Add client request duration metric. ([#4132](googleapis/sdk-platform-java#4132)) ([487650e](googleapis/sdk-platform-java@487650e)) * Add more attributes to golden signals metrics. ([#4135](googleapis/sdk-platform-java#4135)) ([bc82dcb](googleapis/sdk-platform-java@bc82dcb)) * **gax-httpjson:** add HttpJsonErrorParser utility ([#4137](googleapis/sdk-platform-java#4137)) ([6fe2446](googleapis/sdk-platform-java@6fe2446)) * **generator:** add extra allowed modules that will not be removed from the monorepo if they are present ([#4124](googleapis/sdk-platform-java#4124)) ([6a440da](googleapis/sdk-platform-java@6a440da)) * **o11y:** introduce `gcp.client.repo` and `gcp.client.artifact` attributes ([#4120](googleapis/sdk-platform-java#4120)) ([4954de5](googleapis/sdk-platform-java@4954de5)) * **o11y:** Introduce `rpc.system.name` and `rpc.method` in gRPC ([#4121](googleapis/sdk-platform-java#4121)) ([3593c30](googleapis/sdk-platform-java@3593c30)) * **o11y:** introduce server.port attribute ([#4128](googleapis/sdk-platform-java#4128)) ([1b10e02](googleapis/sdk-platform-java@1b10e02)) ### Bug Fixes * add null checks for ApiTracerFactory in ClientContext ([#4122](googleapis/sdk-platform-java#4122)) ([ded1922](googleapis/sdk-platform-java@ded1922)) * Decrease log level for directpath warnings outside GCE ([#4139](googleapis/sdk-platform-java#4139)) ([5151f34](googleapis/sdk-platform-java@5151f34)) * **gax-grpc:** add pick_first fallback to direct path service config ([#4143](googleapis/sdk-platform-java#4143)) ([4934ad8](googleapis/sdk-platform-java@4934ad8)) * Populate method level attributes in metrics recording ([#4149](googleapis/sdk-platform-java#4149)) ([69aabf8](googleapis/sdk-platform-java@69aabf8)) * suppress warnings in generated projects for non-idiomatic durations ([#4119](googleapis/sdk-platform-java#4119)) ([8a0c565](googleapis/sdk-platform-java@8a0c565)) * Use ServiceName + MethodName as the regex for Otel ([#2543](googleapis/sdk-platform-java#2543)) ([8196b8f](googleapis/sdk-platform-java@8196b8f)) ### Documentation * **hermetic_build:** fix config field name in readme ([#4130](googleapis/sdk-platform-java#4130)) ([0d98c37](googleapis/sdk-platform-java@0d98c37)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

product-auto-label Bot added the size: m Pull request size is medium. label Mar 11, 2026

westarle marked this pull request as draft March 11, 2026 21:47

gemini-code-assist Bot reviewed Mar 11, 2026

View reviewed changes

Comment thread gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonErrorParser.java Outdated

westarle force-pushed the feat/actionable-errors-http-parser branch from 65e645a to 0a07d96 Compare March 11, 2026 21:52

feat(gax-httpjson): add HttpJsonErrorParser utility

d62f1f0

westarle force-pushed the feat/actionable-errors-http-parser branch from 0a07d96 to d62f1f0 Compare March 11, 2026 21:55

westarle added 2 commits March 12, 2026 07:56

fix(gax-httpjson): fix actionable errors test assertions and logic

b43eea1

Merge branch 'main' into feat/actionable-errors-http-parser

e44d116

westarle marked this pull request as ready for review March 12, 2026 12:38

westarle requested review from blakeli0 and diegomarquezp March 12, 2026 15:02

blakeli0 reviewed Mar 12, 2026

View reviewed changes

westarle added 6 commits March 13, 2026 13:33

impl(gax-httpjson): address review feedback for HttpJsonErrorParser

3659941

docs(gax-httpjson): document AIP-193 as the standard error format in …

8e10737

…HttpJsonErrorParser

docs(gax-httpjson): address Javadoc formatting feedback

50cfee9

test(gax-httpjson): add edge case tests for HttpJsonErrorParser

8029732

impl(gax-httpjson): return empty ErrorDetails for garbage data instea…

ec3b60a

…d of throwing RuntimeException

impl(gax-httpjson): return empty ErrorDetails for all parsing problem…

49b5f46

…s and localize catches

product-auto-label Bot added size: l Pull request size is large. and removed size: m Pull request size is medium. labels Mar 13, 2026

format(gax-httpjson): run google-java-format to fix CI errors

fcf5e78

product-auto-label Bot added size: m Pull request size is medium. and removed size: l Pull request size is large. labels Mar 13, 2026

impl: refactor HttpJsonErrorParser to return google.rpc.Status and re…

b5c1f2d

…name method to parseStatus

product-auto-label Bot added size: l Pull request size is large. and removed size: m Pull request size is medium. labels Mar 13, 2026

westarle added 2 commits March 13, 2026 15:29

chore: fix formatting in HttpJsonErrorParserTest.java

f1448c8

chore: remove unused LOGGER from HttpJsonErrorParser

f2dd40c

westarle commented Mar 13, 2026

View reviewed changes

chore: fix formatting in HttpJsonErrorParser and test

627d68a

westarle requested a review from blakeli0 March 13, 2026 19:52

blakeli0 approved these changes Mar 13, 2026

View reviewed changes

westarle changed the title feat(gax-httpjson): add HttpJsonErrorParser utility impl(gax-httpjson): add HttpJsonErrorParser utility Mar 14, 2026

westarle changed the title impl(gax-httpjson): add HttpJsonErrorParser utility feat(gax-httpjson): add HttpJsonErrorParser utility Mar 14, 2026

westarle merged commit a1b7565 into googleapis:main Mar 14, 2026
49 of 51 checks passed

release-please Bot mentioned this pull request Mar 11, 2026

chore(main): release 2.68.0 #4123

Merged

+                 */
+                public static ErrorDetails parseErrorDetails(String errorJson) {
+                  if (errorJson == null || errorJson.isEmpty()) {
+                    return null;

+                private static final TypeRegistry ERROR_INFO_REGISTRY =
+                    TypeRegistry.newBuilder().add(ErrorInfo.getDescriptor()).build();
+                private static final JsonFormat.Parser JSON_PARSER =
+                    JsonFormat.parser().ignoringUnknownFields().usingTypeRegistry(ERROR_INFO_REGISTRY);

+                    ErrorDetails.Builder errorDetailsBuilder = ErrorDetails.builder();
+                    errorDetailsBuilder.setRawErrorMessages(status.getDetailsList());
+                    return errorDetailsBuilder.build();
+                  } catch (InvalidProtocolBufferException e) {

+                    errorDetailsBuilder.setRawErrorMessages(status.getDetailsList());
+                    return errorDetailsBuilder.build();
+                  } catch (InvalidProtocolBufferException e) {
+                    LOGGER.log(Level.WARNING, "Failed to parse Google Cloud error response", e);

+                 */
+                public static ErrorDetails parseErrorDetails(String errorJson) {
+                  if (errorJson == null || errorJson.isEmpty()) {
+                    return null;

+                  try {
+                    JsonObject root = JsonParser.parseString(errorJson).getAsJsonObject();
+                    if (!root.has("error")) {

feat(gax-httpjson): add HttpJsonErrorParser utility by westarle · Pull Request #4137 · googleapis/sdk-platform-java · GitHub

Uh oh!

feat(gax-httpjson): add HttpJsonErrorParser utility - #4137

feat(gax-httpjson): add HttpJsonErrorParser utility#4137westarle merged 14 commits intogoogleapis:maingoogleapis/sdk-platform-java:mainfrom westarle:feat/actionable-errors-http-parserwestarle/sdk-platform-java:feat/actionable-errors-http-parserCopy head branch name to clipboard

Conversation

westarle commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context & Future Use

Testing

Uh oh!

gemini-code-assist Bot commented Mar 11, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

westarle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blakeli0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(gax-httpjson): add HttpJsonErrorParser utility#4137
westarle merged 14 commits into
googleapis:mainfrom
westarle:feat/actionable-errors-http-parser

westarle commented Mar 11, 2026 •
edited
Loading