feat!: Support AIP-193 for `GaxiosError` by d-goog · Pull Request #699 · googleapis/gaxios

d-goog · 2025-05-23T14:51:38Z

Description

Adds AIP-193 recommendations to GaxiosError, including:

Surfacing API error messages as its message (Error.message)
Adding the content of the API error into Gaxios's cause property, which has first-class logging support in many environments (Error.cause)

History

Previously, some of this functionality was in google-auth-library within its now-removed transporter. It was within the transporter this logic predates this library itself (we were using request and axios at the time) and auth was the closest place to put such logic. This logic can now live where it belongs - gaxios.

Some additional references for background:

refactor!: Remove Transporter google-auth-library-nodejs#1937
- See src/transporters.ts
https://github.com/googleapis/google-auth-library-nodejs/blob/14009b9fedb6c3fa755e4133640a39c3209fae19/lib/transporters.js
- A historical example of the AIP's usage in wrapCallback_ pre-gaxios
build: update gaxios & gcp-metadata to 6.0.0, update @types/node to 20.4.2, decrease puppeteer to ^19.0.0, distinguish status and code in error handling. google-auth-library-nodejs#1592
- Added additional status/code support for the returned errors

Impact

This will improve the debugging experience for customers as the API-level error is easy to see while the GaxiosError context/details are preserved.

Testing

Updated tests to reflect. Note: many tests did not require changing as it is mostly backwards-compatible.

Additional Information

Fixes #572
Fixes #684

🦕

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

…nto aip-193-gaxios-error

generated-files-bot · 2025-05-23T14:54:34Z

Warning: This pull request is touching the following templated files:

README.md - README.md is managed by synthtool. However, a partials file can be used to update the README, e.g.: https://github.com/googleapis/nodejs-storage/blob/main/.readme-partials.yaml

d-goog · 2025-05-23T14:56:15Z

test/test.getch.ts

-          err.response?.data.error.message === 'File not found'
-        );
+
+        assert.deepStrictEqual(err.cause, body.error);


Note: this assert works within the callback context as assert.rejects handles it properly.

d-goog · 2025-05-23T14:58:49Z

src/retry.ts

-    (err.config.signal?.aborted && err.error?.name !== 'TimeoutError') ||
-    err.name === 'AbortError' ||
-    err.error?.name === 'AbortError'
+    (err.config.signal?.aborted && err.code !== 'TimeoutError') ||
+    err.code === 'AbortError'


A few things here:

name could never be AbortError (always GaxiosError)

We can demonstrate best practices by not referencing the deprecated GaxiosError#error

Notice the relevant retry tests did not need to change for this logic

d-goog · 2025-05-23T15:01:29Z

src/gaxios.ts

+      let err: GaxiosError;
+
+      if (e instanceof GaxiosError) {
+        err = e;
+      } else if (e instanceof Error) {
+        err = new GaxiosError(e.message, opts, undefined, e);
+      } else {
+        err = new GaxiosError('Unexpected Gaxios Error', opts, undefined, e);
+      }


Summary:

in the first case we're using the existing GaxiosError

in the second we're adopting an existing Error's message

in the third some random, non-Error must've been thrown

Note:

GaxiosError supports e as unknown

d-goog · 2025-05-23T15:02:12Z

src/common.ts

+   * @internal
+   * @expiremental


We can open this up for external libraries later, if needed

d-goog · 2025-05-23T15:04:40Z

src/common.ts

+    if (cause instanceof DOMException) {
+      // The DOMException's equivalent to code is its name
+      // E.g.: name = `TimeoutError`, code = number
+      // https://developer.mozilla.org/en-US/docs/Web/API/DOMException/name
+      this.code = cause.name;
+    } else if (
+      cause &&
+      typeof cause === 'object' &&
+      'code' in cause &&
+      typeof cause.code === 'string'
+    ) {
+      this.code = cause.code;
+    }


Improved accuracy and type-checking as cause is unknown. DOMException is the only standard Error instance that has a numeric code rather than a string (and that property is deprecated).

d-goog · 2025-05-23T15:05:11Z

README.md

 ## License

-[Apache-2.0](https://github.com/googleapis/gaxios/blob/master/LICENSE)
+[Apache-2.0](https://github.com/googleapis/gaxios/blob/main/LICENSE)


linkinator complaint

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

d-goog · 2025-05-23T16:14:09Z

.github/scripts/package.json

    },
    "devDependencies": {
-        "@octokit/rest": "^21.0.0",
+        "@octokit/rest": "^19.0.0",


sofisl · 2025-05-23T17:30:51Z

src/common.ts

+      cause &&
+      typeof cause === 'object' &&
+      'code' in cause &&
+      typeof cause.code === 'string'


Suggested change

typeof cause.code === 'string'

Currently code comes as int32 so this would cause code to be undefined in a lot of places.

src/common.ts

sofisl

These changes mirror the previous processError function and pass current tests in google-api-nodejs-client.

sofisl · 2025-05-23T19:22:21Z

Commenting here so we can remember...

It looks like the decision between returning error as code or string was already a discussion, Ben brought up the point that it could/should be either so let's just pass it through (without type-checking).

…nto aip-193-gaxios-error

Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com>

feat!: Support AIP-193 for GaxiosError

5e2955f

d-goog requested a review from a team as a code owner May 23, 2025 14:51

product-auto-label bot added the size: m Pull request size is medium. label May 23, 2025

gcf-owl-bot bot and others added 3 commits May 23, 2025 14:54

🦉 Updates from OwlBot post-processor

1bae2c1

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

docs: linkinator

33321c0

Merge branch 'aip-193-gaxios-error' of github.com:googleapis/gaxios i…

806ea10

…nto aip-193-gaxios-error

d-goog changed the title ~~feat!: Support AIP-193 for GaxiosError~~ feat!: Support AIP-193 for GaxiosError May 23, 2025

d-goog commented May 23, 2025

View reviewed changes

d-goog and others added 2 commits May 23, 2025 08:05

chore: undo accidental change

0f3693e

🦉 Updates from OwlBot post-processor

d3e7634

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

d-goog commented May 23, 2025

View reviewed changes

.github/scripts/package.json

},

"devDependencies": {

"@octokit/rest": "^21.0.0",

"@octokit/rest": "^19.0.0",

Copy link

Contributor Author

d-goog May 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

via owlbot

sofisl reviewed May 23, 2025

View reviewed changes

sofisl changed the title ~~feat!: Support AIP-193 for GaxiosError~~ fix!: Support AIP-193 for GaxiosError May 23, 2025

sofisl reviewed May 23, 2025

View reviewed changes

src/common.ts Show resolved Hide resolved

sofisl reviewed May 23, 2025

View reviewed changes

d-goog changed the title ~~fix!: Support AIP-193 for GaxiosError~~ feat!: Support AIP-193 for GaxiosError May 23, 2025

d-goog and others added 3 commits May 23, 2025 12:36

feat: Extend GaxiosError#code to string | number

16eab31

Merge branch 'aip-193-gaxios-error' of github.com:googleapis/gaxios i…

3cfb607

…nto aip-193-gaxios-error

feat: Support top-level message from res.error.data

9028eb5

Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com>

sofisl approved these changes May 23, 2025

View reviewed changes

style: lint

4efce30

d-goog merged commit b6e0032 into main May 23, 2025
14 checks passed

d-goog deleted the aip-193-gaxios-error branch May 23, 2025 19:50

release-please bot mentioned this pull request May 23, 2025

chore(main): release 7.0.0 #657

Merged

leahecole mentioned this pull request May 27, 2025

Some unit tests in grpc-fallback fail silently googleapis/google-cloud-node-core#182

Closed

sofisl mentioned this pull request May 28, 2025

feat!: upgrade to node 18 googleapis/google-api-nodejs-client#3658

Merged

MarkDuckworth mentioned this pull request Nov 3, 2025

retries not working with gaxioserror in gaxios v7 googleapis/google-cloud-node-core#173

Closed

7 tasks

Conversation

d-goog commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

History

Impact

Testing

Additional Information

Uh oh!

generated-files-bot bot commented May 23, 2025

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!

Uh oh!

sofisl left a comment

Choose a reason for hiding this comment

Uh oh!

sofisl commented May 23, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

d-goog commented May 23, 2025 •

edited

Loading