Zuvo Docs

Guide

Error Codes

Learn about the Auth error codes and how to resolve them

Auth error codes

Zuvo Auth can return various errors when using its API. This guide explains how to handle these errors effectively across different programming languages.

Error types

Zuvo Auth errors are generally categorized into two main types:

  • API Errors: Originate from the Zuvo Auth API.
  • Client Errors: Originate from the client library's state.

Client errors differ by language so do refer to the appropriate section below:

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 Zuvo 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 Zuvo Auth:

403 Forbidden

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

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

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

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

Sent out when a feature is not enabled on the Auth server, and you are trying to use an API which requires it.

Auth error codes table

The following table provides a comprehensive list of error codes you may encounter when working with Zuvo Auth. Each error code is associated with a specific issue and includes a description to help you understand and resolve the problem efficiently.

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.