Error handling with refreshTokenGrant

[aza547]

What happened?

Hello,

Thanks for the library. I'm a bit unsure of the right way to handle errors with the refreshTokenGrant method. I'm not sure if this is a bug so hope you will forgive the issue if not. Ultimately I want to do this...

try {
  await refreshTokenGrant(...)
} catch (error) {
  if (error.intermittent) {
     // retry later
  } else {
     // delete refresh token and log user out
  }
} 

The docs don't make it clear on what refreshTokenGrant throws however.

I had a poke about in the source (read errorHandler) and I can see that it is rethrowing errors from the oauth4webapi library in many cases (so I could try install that library and catch those errors) but there is another ClientError type too.

So my question ultimately is what is the right way to do this? And assuming you agree with the above the request is for the docs to make that clear. Please tell me if I'm doing something stupid.

Many thanks

Version

v6.8.4

Runtime

Select an option

Runtime Details

Node 24

Code to reproduce

See above.

Required

• I have searched the issues tracker and discussions for similar topics and couldn't find anything related.
• I agree to follow this project's Code of Conduct

[sueun-dev]

yeah, looks like there isn't one error.intermittent flag to key off here.

I checked current main at 1e970f2 and also ran a tiny fake token-endpoint test against refreshTokenGrant(): a 400 OAuth JSON body with invalid_grant comes through as ResponseBodyError, with error, error_description, status, response, and cause available. So I'd branch on that first: invalid_grant is the throw-away-token / re-auth case, while token endpoint errors like temporarily_unavailable are the retry-later bucket.

For local/client/runtime failures, check ClientError / TypeError plus error.code and error.cause. Current source normalizes timeout and abort into OAUTH_TIMEOUT / OAUTH_ABORT.

[aza547]

Thanks, that line up with what I saw too. I still think this should be documented behaviour though because this is quite a standard part of the management lifecycle and having to dig around in the source to work out what errors and properties to check seems like it will lead to bugs.