Authentication error messages poorly/not documented

[LukeHosk]

Improve documentation

Link

Could potentially go in multiple places, e.g. just for email/password login auth docs or client docs.

Describe the problem

The potential return values of most of the auth functions are not documented, which makes it hard to handle potential errors client-side.

Describe the improvement

Include details of the potential messages the auth functions can return.

Could alternatively link to the gotrue docs if you wish to maintain a separation, however they would also need to be improved first as they currently list the only possible response as 200 success

Additional context

After manually working up through the dependancy tree to try and document the potential errors for the supabase-js signInWithPassword function figure out how to handle them in my project, i came up with the following list (links are to the part of the code that returns the error):

• 'You must provide either an email or phone number and a password' (comes from gotrue-js all others from gotrue)
• 'Email logins are disabled'
• 'Database error querying schema'
• 'Email not confirmed'
• 'Failed to set JWT cookie'
• 'Invalid login credentials' - shown when
  • Provided email was the empty string
  • no user matching the provided email was found
  • user is banned
  • verification failed
  • incorrect password

[LukeHosk]

I have tried to have a look at starting to add this myself, but can't figure out where the information should go. best guess would be the 'response' section for the api docs?

[encima]

Thanks for opening this, to get started with docs you can check out the Getting Started guide (notably, the Federated Docs section linked)

[charislam]

Hey @LukeHosk, thanks for pointing this out! The team is aware of this and are working on standardizing error messages. It might make most sense to wait for the standardization to be completed before documenting

[AbdulrahmanNahhas]

Hey @LukeHosk, thanks for pointing this out! The team is aware of this and are working on standardizing error messages. It might make most sense to wait for the standardization to be completed before documenting

Hello @charislam, How much time do you estimate the team will need to complete the standardization process?

[charislam]

Thanks @AbdulrahmanNahhas for the reminder to circle back on this! The error codes are now documented here: https://supabase.com/docs/reference/javascript/auth-error-codes

[superakabo]

Hi @charislam, The error codes are too generic and that's not really helpful.
For example, while working with the Auth API, 403 Forbidden was thrown many times for so many reasons. It would be nice to have unique error codes for most of these scenarios and not a generic "403 Forbidden" error code. I also realized on a number of occasions that errors were thrown without an error code. The docs discourage us from relying on the error messages but at the moment you leave us with no choice.

[charislam]

Hi @superakabo, did you see the string codes from that section? For example bad_code_verifier. Those are the ones you should rely on as they are stable and more specific than the HTTP status codes. (Notice it is the codes, not the error messages, which indeed as you say are discouraged because they aren't stable.)

[superakabo]

@charislam I understand what you're saying and that's what I expect but sadly this is the reality

AuthApiException (AuthException(message: Invalid login credentials, statusCode: 400))

I got this from the Flutter SDK. There's nothing like that present.

[charislam]

Thanks @superakabo! That is super clear. I've spoken to the Auth team and I believe this is a known bug that they have a pending fix for: supabase/auth#1721

[dshukertjr]

@superakabo Could you confirm that you are on the latest version of supabase-flutter? If not, could you upgrade it to the latest version and try it out?

[superakabo]

Hi @dshukertjr I have tried the latest version of supabase-flutter and the issue still exists.

AuthApiException (AuthException(message: Invalid login credentials, statusCode: 400, errorCode: null))