apps/docs/content/guides/auth/debugging/error-codes.mdx
Supabase Auth can return various errors when using its API. This guide explains how to handle these errors effectively across different programming languages.
Supabase Auth errors are generally categorized into two main types:
Client errors differ by language so do refer to the appropriate section below:
<Tabs scrollable size="small" type="underlined"
<TabPanel id="javascript" label="JavaScript"> All errors originating from the `supabase.auth` namespace of the client library will be wrapped by the `AuthError` class.
Error objects are split in a few classes:
AuthApiError -- errors which originate from the Supabase Auth API.
isAuthApiError instead of instanceof checks to see if an error you caught is of this type.CustomAuthError -- errors which generally originate from state in the client library.
name property on the error to identify the class of error received.Errors originating from the server API classed as AuthApiError always have a code property that can be used to identify the error returned by the server. The status property is also present, encoding the HTTP status code received in the response.
Error objects are split in a few classes. AuthApiException is an exception which originates from the Supabase Auth API.
Errors originating from the server API classed as AuthApiException always have a code property that can be used to identify the error returned by the server. The statusCode property is also present, encoding the HTTP status code received in the response.
The api(message:errorCode:underlyingData:underlyingResponse:) case is a special case for errors which originates from the Supabase Auth API, this error always have an errorCode property that can be used to identify the error returned by the server.
Error objects are split in a few classes. AuthApiError is an error which originate from the Supabase Auth API.
Errors originating from the server API classed as AuthApiError always have a code property that can be used to identify the error returned by the server. The status property is also present, encoding the HTTP status code received in the response.
Rest exceptions are split into a few classes:
AuthRestException -- exceptions which originate from the Supabase Auth API and have a errorCode property that can be used to identify the error returned by the server.AuthWeakPasswordException -- an AuthRestException which indicates that the password is too weak.AuthSessionMissingException -- an AuthRestException which indicates that the session is missing, if the user was logged out or deleted.All instances and subclasses of a AuthRestException have a errorCode property that can be used to identify the error returned by the server.
Below are the most common HTTP status codes you might encounter, along with their meanings in the context of Supabase Auth:
Sent out in rare situations where a certain Auth feature is not available for the user, and you as the developer are not checking a precondition whether that API is available for the user.
Sent out when the API request is accepted, but cannot be processed because the user or Auth server is in a state where it cannot satisfy the request.
Sent out when rate-limits are breached for an API. You should handle this status code often, especially in functions that authenticate a user.
Indicate that the Auth server's service is degraded. Most often it points to issues in your database setup such as a misbehaving trigger on a schema, function, view or other database object.
Sent out when a feature is not enabled on the Auth server, and you are trying to use an API which requires it.
The following table provides a comprehensive list of error codes you may encounter when working with Supabase Auth. Each error code is associated with a specific issue and includes a description to help you understand and resolve the problem efficiently.
<ErrorCodes service="auth" />error.code and error.name to identify errors, not string matching on error messages.