diff --git a/apps/docs/components/MDX/auth_error_codes_table.mdx b/apps/docs/components/MDX/auth_error_codes_table.mdx index 8c44aaf4cfc..01320a9ed3f 100644 --- a/apps/docs/components/MDX/auth_error_codes_table.mdx +++ b/apps/docs/components/MDX/auth_error_codes_table.mdx @@ -1,11 +1,3 @@ -In general the HTTP status codes you will likely receive are: - -- [403 Forbidden](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) is 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. -- [422 Unprocessable Entity](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) is 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. -- [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) is sent out when rate-limits are breached for an API. You should handle this status code often, especially in functions that authenticate a user. -- [500 Internal Server Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) often means 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. -- [501 Not Implemented](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501) is sent out when a feature is not enabled on the Auth server, and you are trying to use an API which requires it. - To supplement HTTP status codes, Supabase Auth returns a string error code which gives you more insight into what went wrong. These codes are stable and can be used to present an internationalized message to your users. | Code | Description | diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index d074fe8e7a0..7692f366e14 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -504,6 +504,7 @@ export const auth = { }, ], }, + { name: 'Concepts', items: [ @@ -583,6 +584,10 @@ export const auth = { }, ], }, + { + name: 'Debugging', + items: [{ name: 'Error Codes', url: '/guides/auth/debugging/error-codes' }], + }, { name: 'Third-party auth', items: [ diff --git a/apps/docs/content/guides/auth/debugging/error-codes.mdx b/apps/docs/content/guides/auth/debugging/error-codes.mdx new file mode 100644 index 00000000000..1ee94673d5d --- /dev/null +++ b/apps/docs/content/guides/auth/debugging/error-codes.mdx @@ -0,0 +1,104 @@ +--- +id: 'auth-error-codes' +title: 'Error Codes' +description: 'Supabase Auth Error Codes' +subtitle: 'Learn about the Auth error codes and how to resolve them' +--- + +## Auth Error Codes + +Supabase Auth can return various errors when using its API. This guide explains how to handle these errors effectively across different programming languages. + +## Error Types + +Supabase Auth errors are generally categorized into two main types: + +- API Errors: Originate from the Supabase Auth API. +- Client Errors: Originate from the client library's state. + +Client errors differ by language so do refer to the appropriate section below: + + + +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. + - Use `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. + - Use the `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. + + + +All errors originating from the `supabase.auth` namespace of the client library will be wrapped by the `AuthException` class. + +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. + + + +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` 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. + + + +All errors originating from the `supabase.auth` namespace of the JavaScript 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. + - Use `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. + - Use the `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. + + + + + +## HTTP Status Codes + +Below are the most common HTTP status codes you might encounter, along with their meanings in the context of Supabase Auth: + +### [403 Forbidden](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) + +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. + +### [422 Unprocessable Entity](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) + +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. + +### [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) + +Sent out when rate-limits are breached for an API. You should handle this status code often, especially in functions that authenticate a user. + +### [500 Internal Server Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) + +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. + +### [501 Not Implemented](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501) + +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. + +## Auth Error Codes Table + + + +## Best Practices for Error Handling + +- Always use `error.code` and `error.name` to identify errors, not string matching on error messages. +- Avoid relying solely on HTTP status codes, as they may change unexpectedly. diff --git a/apps/docs/docs/ref/dart/auth-error-codes.mdx b/apps/docs/docs/ref/dart/auth-error-codes.mdx deleted file mode 100644 index 5708828d29a..00000000000 --- a/apps/docs/docs/ref/dart/auth-error-codes.mdx +++ /dev/null @@ -1,12 +0,0 @@ -Supabase Auth can throw or return various errors when using the API. All errors originating from the `supabase.auth` namespace of the client library will be wrapped by the `AuthException` class. - -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. - - - -### Tips for better error handling - -- Do not use string matching on error messages! Always use the error classes and `code` properties of error objects to identify the situation. -- Although HTTP status codes generally don't change, they can suddenly change due to bugs, so avoid relying on them unless absolutely necessary. diff --git a/apps/docs/docs/ref/javascript/auth-error-codes.mdx b/apps/docs/docs/ref/javascript/auth-error-codes.mdx deleted file mode 100644 index 599bd09e5e0..00000000000 --- a/apps/docs/docs/ref/javascript/auth-error-codes.mdx +++ /dev/null @@ -1,17 +0,0 @@ -Supabase Auth can throw or return various errors when using the API. 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. - - Use `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. - - Use the `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. - - - -### Tips for better error handling - -- Do not use string matching on error messages! Always use the `name` and `code` properties of error objects to identify the situation. -- Although HTTP status codes generally don't change, they can suddenly change due to bugs, so avoid relying on them unless absolutely necessary. diff --git a/apps/docs/docs/ref/kotlin/auth-error-codes.mdx b/apps/docs/docs/ref/kotlin/auth-error-codes.mdx deleted file mode 100644 index 69ff9aacb66..00000000000 --- a/apps/docs/docs/ref/kotlin/auth-error-codes.mdx +++ /dev/null @@ -1,17 +0,0 @@ -Supabase Auth can throw or return various errors when using the API. All errors originating from the `supabase.auth` namespace of the JavaScript 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. - - Use `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. - - Use the `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. - - - -### Tips for better error handling - -- Do not use string matching on error messages! Always use the `name` and `code` properties of error objects to identify the situation. -- Although HTTP status codes generally don't change, they can suddenly change due to bugs, so avoid relying on them unless absolutely necessary. diff --git a/apps/docs/docs/ref/python/auth-error-codes.mdx b/apps/docs/docs/ref/python/auth-error-codes.mdx deleted file mode 100644 index 47e1c63bda9..00000000000 --- a/apps/docs/docs/ref/python/auth-error-codes.mdx +++ /dev/null @@ -1,12 +0,0 @@ -Supabase Auth can throw or return various errors when using the API. 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` 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. - - - -### Tips for better error handling - -- Do not use string matching on error messages! Always use the `name` and `code` properties of error objects to identify the situation. -- Although HTTP status codes generally don't change, they can suddenly change due to bugs, so avoid relying on them unless absolutely necessary. diff --git a/apps/docs/spec/common-client-libs-sections.json b/apps/docs/spec/common-client-libs-sections.json index a1f249de8ac..ac715b2049f 100644 --- a/apps/docs/spec/common-client-libs-sections.json +++ b/apps/docs/spec/common-client-libs-sections.json @@ -396,21 +396,6 @@ "slug": "auth-api", "type": "function" }, - { - "id": "auth-error-codes", - "title": "Error codes", - "slug": "auth-error-codes", - "type": "markdown", - "excludes": [ - "reference_csharp_v0", - "reference_csharp_v1", - "reference_dart_v1", - "reference_javascript_v1", - "reference_kotlin_v1", - "reference_swift_v1", - "reference_swift_v2" - ] - }, { "id": "sign-up", "title": "Create a new user",