Error Handling

Most endpoints return errors as JSON with the same shape:

{
  "error": "invalid_credentials",
  "message": "Invalid email or password"
}

error is the stable machine-readable code. Match on it, not message; the message is for people and can change. The HTTP status provides the usual API signal (404 not found, 409 conflict, 429 rate limited, and so on).

This page covers runtime errors from mounted HTTP handlers. For configuration errors returned by NewConfig before the server starts, see Configuration.

Handling errors programmatically

Direct service calls such as auth.Register(...), auth.Services.Auth.Login(...), and auth.Services.Admin.BanUser(...) return a normal Go error, not the JSON envelope. Library errors are *domain.AuthError values with Code and Message; they intentionally do not contain an HTTP status. The built-in handlers derive a status from Code.

result, err := auth.Services.Auth.Login(ctx, goauth.LoginInput{Email: email, Password: password})
if err != nil {
    if errors.Is(err, domain.ErrInvalidCredentials) {
        // matches the exported sentinel for this fixed error
    }

    var authErr *domain.AuthError
    if errors.As(err, &authErr) {
        // Same pair as the JSON envelope's "error" and "message" fields.
        // The tables on this page map each code to an HTTP status.
    }
}

Use errors.Is for one specific outcome, such as domain.ErrInvalidCredentials. Use errors.As when you need the code and message generically. This is also how the handlers map an error to a response; an error that is not a *domain.AuthError becomes internal_error (500). Prefer errors.As to a direct type assertion because it also finds an *AuthError inside a wrapped error.

Not every layer uses this shape

Two paths do not use the JSON envelope:

• CSRF origin/token middleware (middleware.OriginCheck, middleware.CSRFToken) responds with a plain-text body via http.Error, e.g. Forbidden - CSRF headers missing (403), not JSON. It runs ahead of your handlers and has no domain error to format.
• OAuth callback errors are never returned as a JSON body at all. The browser is mid-redirect at that point. They come back as a redirect to {BaseURL}/auth/callback?error={code}&provider={provider}, and your frontend reads error from the query string.

Organization membership middleware (middleware.RequireOrgMember, RequireOrgRole) uses the normal envelope. A non-member receives org_member_not_found (404); an under-privileged member receives org_forbidden (403).

All remaining service and handler errors use the {"error", "message"} envelope.

General

internal_error always means: something failed that the caller cannot fix by changing their request (a database error, a failed hash, etc.). It is logged server-side with detail; the client only ever sees the generic message.

Authentication (register, login, session cookie)

Two-factor authentication

Sessions

Password

Account (name, deletion, email verification)

Invites (self-service, invite-only signup)

OAuth

Callback errors do not arrive as JSON. See Not every layer uses this shape above.

Organizations

The org-membership middleware (RequireOrgMember, RequireOrgRole) uses the normal envelope too. See Not every layer uses this shape above: a non-member gets the same org_member_not_found 404 a direct OrgService call returns, and an under-privileged member gets org_forbidden 403.

Admin

CSRF and rate limiting

These respond outside the JSON envelope or with a narrower one. See Not every layer uses this shape for the CSRF middleware specifics.