feat: add error codes

[hf]

Adds proper error codes with API versioning.

From now on, all responses that end in a 4XX HTTP status code will include a textual description of the error that occurred.

Error responses on API versions before 2024-01-01 have this schema:

{
  "code": "<http status code>",
  "msg": "<descriptive error message>",
  "error_code": "<textual error code>"
}

Error responses on API version on or after 2024-01-01 have this schema:

{
  "code": "<textual error code>",
  "message": "<descriptive error message>"
}

API versions are controlled by submitting an X-Supabase-Api-Version header to the request. A missing or invalid value assumes the "initial" API version as used before the introduction of API version 2024-01-01.

Error code contract for API version 2024-01-01:

1. Error codes will not be renamed. You can safely rely on them.
2. HTTP status codes are mostly fixed, but you should not rely on them except the class 4XX vs 5XX.
3. Error messages are a developer aid. They may change across deployed version. You should not rely on them, but if you want you can show them to your users. Error translations should be based on the error code!

Of the 4XX HTTP status code class, only these codes are allowed to be used in API version 2024-01-01 according to these rules. The purpose of this is to keep proper HTTP semantics. The tuple (http_status_code, error_code) shouldn't be used by clients!

HTTP Status Code	When to use?	Primary Fault At
400 Bad Request	Inputs (body, headers) and their contents are not valid as a whole, or parts of them. Example: bad JSON, bad JSON object, using two mutually exclusive JSON fields, missing required fields, wrong encoding… If the answer to this question is yes then you should probably use 400: Is there some technical thing the developer should do to get a different status code?	Developer. MUST NEVER OCCUR WHEN USING AN OFFICIAL SUPABASE LIBRARY. Why? - Library should not send invalid requests. - If occurring, means: improper types, no client-side validation.
401 Unauthorized	You must use this code if security headers or inputs are missing, and are not valid to some extent. Example: missing JWT, missing CAPTCHA token, missing important query params that serve to authenticate the caller. You may use 400 instead if the security headers or inputs are provided and relatively valid (valid JWT signature, bad claims) instead, though prefer 401 over 400 unless it aids in DX. Do not use this code to signal that the user does not have sufficient application privileges. If the answer to this question is yes then you should use 401: Are the credentials the user/client sending missing or invalid in form, structure, encoding?	Developer. MUST NEVER OCCUR WHEN USING AN OFFICIAL SUPABASE LIBRARY. Why? - Library should never send improper requests (missing authorization headers for features that require authorization). - If occurring means: broken logic, improper types, no client-side validation.
403 Forbidden	Do not use this code for bad JWT format, missing headers or other validation on security sensitive payloads. Return 400 on those. Once security payloads have been validated in structure, only return this error if the user/client can be authenticated properly but they do not possess the proper authorization to access the resource. If the answer to this question is yes then you should use 403: Should the user/client be someone else to get a different status code? In some cases you should prefer 200 responses with empty bodies, akin to RLS behavior.	User. Developer is at fault for not hiding the feature sufficiently. Can rarely occur when using Supabase libraries, and in such cases it means docs / explanation problems.
404 Not Found	Do not use this for missing objects in the database. Prefer using 422 instead. Use only if the URL cannot be fully validated, resulting in a resource that cannot be properly identified. If there’s no variables in the path, this code must not be used. Good: - /users/<not-uuid> - /users/<uuid> (but such a user does not exist) Bad: - /token?grant_type=password (no variables in URL) - /sessions (no variables in URL) For cases where a feature is disabled on a server consider using 501 or 422. For requests that “look up” entities consider using 200 with an empty/null response body or 204 No Content instead.	Developer. MUST NEVER OCCUR WHEN USING AN OFFICIAL SUPABASE LIBRARY. Why? - Library should never send improperly formatted URLs, or encode data in URLs that it knows to be invalid. - Ideally library should not take in freeform input about entities, and should use some “proof” that the entity exists. Example: calling methods on objects returned by a list/find-by-id method. - In some situations it’s inevitable (like in admin APIs).
422 Unprocessable Entity	Do not use for bad inputs! Once all inputs to a request have been validated to the fullest extent possible (e.g. OK to validate an email address format, but not necessary to validate that there’s a SMTP server listening), use this status code to signal errors with the processing logic. This includes all logic dependent on database state (user exists, or doesn’t). All third-party expected errors (like calling into a third service) should end with 422. If the answer to this question is yes then you should use 422: Is there something different that the user should do to get a different status code?	User. Developer is at fault for using the feature in an improper part of the flow. Can rarely occur when using Supabase libraries, and in such cases it means docs / explanation problems.
429 Too Many Requests	Only use this for rate-limiting or other cases that limit the number of requests. Third-party rate-limits should be propagated with this error.	User. Developer should have implemented a better UX to prevent reaching this error for legitimate users. (Disabling buttons, adding timeout UI elements…)
500 Internal Server Error	Use this for any unexpected errors when processing a request. Default to this code if you can’t find a 4XX error code for it.	Supabase. Developer in some cases (such as when changing database contents). The cause of this error should not be situations arising from official Supabase libraries (such as sending inputs that crash the server).
501 Not Implemented	A feature is disabled, not configured (properly), blocked or otherwise unavailable.	Developer, for not enabling or configuring features properly.

[tom-at-pixel]

Very nice and granular error codes! This will bring the DX of Supabase's authentication module much closer to that of Firebase. Great work. 😎

[hf]

Very nice and granular error codes! This will bring the DX of Supabase's authentication module much closer to that of Firebase. Great work. 😎

Note that at this point these are just extractions, they're not definitive in shape or form.

[kangmingtay]

would be great if we can create an ErrorCode type for this instead of using normal strings for ease of maintainability

[J0]

Thanks! This looks fine to me - will do another pass later in day and open PR if needed

[mashwishi]

is this only for auth-js ? and supabase-js not included?

            const response = await supabase.auth.signInWithPassword({
                email: email,
                password: password,
            })

This is currently "@supabase/supabase-js": "^2.41.1"

[haydn]

@mashwishi From your code snippet I don't really understand how that log message is getting generated, but I believe that AuthApiError object will have a code property on it you can use.

Something like this:

console.log(response.error.code);

[mashwishi]

@mashwishi From your code snippet I don't really understand how that log message is getting generated, but I believe that AuthApiError object will have a code property on it you can use.

Something like this:

console.log(response.error.code);

Will test that out today.

[mashwishi]

@mashwishi From your code snippet I don't really understand how that log message is getting generated, but I believe that AuthApiError object will have a code property on it you can use.

Something like this:

console.log(response.error.code);

that's weird.

it works on

            console.log({
                'code:': response?.error?.code,
                'name:': response?.error?.name,
                'status:': response?.error?.status,
                'message:': response?.error?.message
            });

with output:

{"code:": undefined, "message:": "Invalid login credentials", "name:": "AuthApiError", "status:": 400}
{"code:": undefined, "message:": "Invalid login credentials", "name:": "AuthApiError", "status:": 400}

But what i am trying to get is proper error code which i get it right now and right error message like example invalid password, account doesnt exist something like that from the auth api.

because if i am going to base it on error code, how would i determine if account doesn't exist or password is incorrect? because they have same output of error message "Invalid credentials" if using error response and "400 error code"