Error Reference

GoAuth uses structured error responses across all modules. Service and HTTP errors use *types.GoAuthError, providing a machine-readable code, a human-readable message, and an HTTP status code.

Lifecycle APIs such as auth.New, Use, Initialize, and Shutdown return ordinary error values. Storage methods use sentinel errors including models.ErrNotFound and models.ErrConflict. Do not assume every error can be directly asserted to *types.GoAuthError.

GoAuthError Struct

type GoAuthError struct {
    Code       ErrorCode `json:"code"`
    Message    string    `json:"message"`
    StatusCode int       `json:"-"`
    Details    any       `json:"details,omitempty"`
    Err        error     `json:"-"`
}

Methods

Error() string -- Implements the error interface. Returns Message if no wrapped error, or "Message: wrapped error" if one exists.

Wrap(err error) *GoAuthError -- Sets the underlying error and returns the same GoAuthError for chaining. Use this to attach a root cause while preserving the structured error:

return types.NewDatabaseError().Wrap(err)

Unwrap() error -- Returns the underlying error, enabling errors.Is() and errors.As() to traverse the error chain:

if errors.Is(authErr.Unwrap(), sql.ErrNoRows) {
    // handle missing row
}

Constructor

func NewGoAuthError(code ErrorCode, message string, statusCode int) *GoAuthError

Creates a custom GoAuthError with any code, message, and status code. Most common errors have dedicated factory functions (listed below).

Standard Error Response

All error responses follow this JSON shape:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error",
  "details": null
}

The details field is omitted from the response when nil. It is populated for specific errors like TWO_FACTOR_REQUIRED, where it carries challenge metadata.

The HTTP status code is set on the response header, not in the JSON body.

Error Codes by Category

User Errors

Authentication Errors

Session Errors

Validation Errors

ErrMissingFields accepts a fields parameter: when provided, the message becomes "Missing required fields: email, password".

ErrInvalidRequestBody is used by NewValidationError(message) which accepts a custom message.

Authorization Errors

Two-Factor Authentication Errors

TWO_FACTOR_REQUIRED uses HTTP 200 intentionally -- it is not an error but a challenge response. The details field carries challenge metadata (e.g. available 2FA methods).

OAuth Errors

Some OAuth factory functions accept a provider or message parameter that is interpolated into the default message.

Organization Errors

Verification Errors

System Errors

Other Errors

NewCustomError(message) creates an error with no HTTP status code set -- the caller is expected to set StatusCode before returning it to an HTTP handler.

Handling Errors in Client Code

Checking Error Codes

if authErr != nil && authErr.Code == types.ErrUserNotFound {
    // handle user not found
}

Wrapping Errors

user, err := db.FindByEmail(ctx, email)
if err != nil {
    return types.NewDatabaseError().Wrap(err)
}

Using errors.Is with Wrapped Errors

authErr := someOperation()
if authErr != nil && errors.Is(authErr, sql.ErrNoRows) {
    // the underlying cause was a missing DB row
}

Factory Functions with Parameters

Several factory functions accept parameters for dynamic messages:

types.NewMissingFieldsError("email, password")
// Message: "Missing required fields: email, password"

types.NewOAuthProviderNotFoundError("github")
// Message: "OAuth provider 'github' not found or not configured"

types.NewInternalError("failed to hash password")
// Message: "failed to hash password"

types.NewValidationError("password must be at least 8 characters")
// Message: "password must be at least 8 characters"