Platform-agnostic errors and types

[thyming]

Checklist

• [X] I have looked into the Readme, Examples, and FAQ and have not found a suitable solution or answer.
• [X] I have looked into the API documentation and have not found a suitable solution or answer.
• [X] I have searched the issues and have not found a suitable solution or answer.
• [X] I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• [X] I agree to the terms within the Auth0 Code of Conduct.

Describe the problem you'd like to have solved

I would like to be able to handle common and expected errors in the auth flow gracefully. For example, if the user closes the login popup, this throws an error, or if a refresh token is expired, this throws an error. However, the error codes and structures are undocumented, platform-specific, and untyped in typescript.

Describe the ideal solution

The error object returned by useAuth0 should be a typed error object with enumerated error codes that are not platform-specific except when strictly necessary. The react SDK does something like this without having the typed error codes, but at least you can reference the oauth error codes from the spec.

One can imagine at least two error classes that this library could implement:

• OAuth error, exactly like the react one, bonus points for enumerating some of the more common spec'ed codes
• CredentialsManager error, perhaps containing an OAuth error as a cause (e.g. refresh token expiration from the server), or something else related to retrieval

Alternatives and current workarounds

The current workaround that we use in our codebase is that we have inspected errors that come out in these cases and reverse engineered the error API from that. Something like:

error && 'code' in error && (error.code === 'a0.session.user_cancelled' || error.code === 'USER_CANCELLED')

which feels quite brittle as an undocumented, platform-specific API.

Additional context

No response

[brunezkey]

We're facing the same problem. We wanted to anticipate which errors we might encounter from the authorize call, but the error types are non-existent.

We also had to manually inspect the errors, but the only one we could consistently reproduce was user_cancelled. Reproducing other types of errors, such as timeouts or issues when the authorization server is down seems very difficult and time-consuming.

Having a typed error object would definitely help us predict which errors to expect and how to respond to them. For now, we will log them and analyze the data over time.

[Manikandan-saminathan]

I'm also encountering the a0.credential_manager.invalid issue in my production application, with various error descriptions, including:

• The credentials renewal failed. CAUSE: Unknown or invalid refresh token.
• An error occurred while trying to use the Refresh Token to renew the Credentials.
• No credentials were found in the store.
• No Credentials were previously set.
• The credentials renewal failed. CAUSE: user is blocked.
• The credentials renewal failed. CAUSE: The request timed out.
• The credentials renewal failed. CAUSE: Unable to complete the operation. CAUSE: SSL error.
• The credentials renewal failed. CAUSE: cannot parse response.

This issue is critical for us, as it affects the reliability of our authentication flow. I would appreciate further support in diagnosing and resolving this issue, as it's impacting our production environment.

For the native side, clear error codes are provided in the documentation: Android and iOS.

If a clear way to handle these errors is provided, it would be very helpful to us.

[Manikandan-saminathan]

I also attempted to handle these errors using error messages but encountered the following issue:

Platform-Specific Error Message:

The SDK returns the same type of error but with two different error descriptions across platforms, making it challenging to handle these errors effectively without consistent error codes.

• Android: “An error occurred while trying to use the Refresh Token to renew the Credentials.”
• iOS: “An error occurred while trying to use the Refresh Token to renew the Credentials.”

iOS-specific error message: No credentials were found in the store. As per the documentation, the reason for failure is not provided.

Android-specific error message: No Credentials were previously set.