Error Handling

The built-in HTTP handlers and middleware 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.

invalid_session_context (400) means X-GoAuth-Session has an unsupported or repeated value, or explicitly selects app on the dedicated admin login route. Omit the header for ordinary app requests; use admin consistently for panel requests.

App authorization

Permission denials and delegation violations use forbidden (403). Privileged calls without required session assurance use two_factor_required (403). Malformed batches/pagination/metadata use invalid_input (400); invalid JSON or unknown management fields use invalid_json (400). Last usable admin reduction uses last_admin (400). Refresh data after a revision conflict; do not blindly overwrite concurrent changes. Missing or disabled business keys deny through RequirePermission, including for admin.

Handling errors programmatically

Import github.com/nazimdjebloun/go-auth/api for the operation input types in Go examples.

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. Auth failures 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, api.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.

Login, session validation, and initial credential-token lookups distinguish an absent row from a backend failure. These backend read failures are wrapped with context while preserving the cause, so direct callers can use errors.Is(err, context.Canceled) or errors.Is(err, context.DeadlineExceeded). Login lookup failures do not become invalid_credentials, and GetSession backend failures do not become session_expired. Mounted handlers return the generic internal_error response for backend failures. Do not assume every service error is a *domain.AuthError, or expose a raw backend error to clients.

HTTP contract and redirect exception

Authentication, authorization, organization, rate-limit, and CSRF middleware use the same two-field JSON envelope as the handlers, with Content-Type: application/json. Clients can decode failures the same way regardless of which layer rejected the request.

OAuth callback failures remain browser redirects, carrying error and provider query parameters on {BaseURL}/auth/callback. Read the query string on that page instead of expecting a JSON body. Direct OAuth service calls still return Go errors.

Errors produced by your own handlers or router, such as an unmatched route or method, are outside this contract. CORS preflight and successful responses keep their existing response formats.

Organization membership middleware returns org_member_not_found (404) for a non-member and org_forbidden (403) for an insufficient role.

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. This includes auth-middleware failures: when session validation, transparent refresh, or the post-rotation user lookup fails because the database is unavailable (or the request context is canceled), the middleware responds 500 internal_error — never a misleading 401. A refresh that has already rotated the session's tokens still delivers the new Set-Cookie headers before that 500, so a client retry uses the current credentials instead of the pre-rotation ones.

password_work_busy means the shared password-work concurrency limit is full; the KDF was not started. It applies to password hashing and verification across HTTP and direct service calls. Use errors.Is(err, domain.ErrPasswordWorkBusy) in Go and retry later with backoff. Login dummy checks propagate the same error; optional rehashing after successful verification may be skipped instead.

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 HTTP contract and redirect exception above.

Organizations

Granular org authorization

Fixed-role and membership errors also apply:

The org-membership middleware (RequireOrgMember, RequireOrgRole) uses the normal envelope too. See HTTP contract and redirect exception 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 failures use the normal JSON envelope. CSRF checks still reject the same requests; only their error representation has changed from plain text to JSON.

Both rate-limit errors include Retry-After. Clients should respect that delay and match the JSON error code, rather than parsing human-readable messages.

Verification required on an existing session

403 email_not_verified means the session is still present but the current email-verification policy forbids protected access. Keep the session and route the user to verification. GET /auth/me returns a minimal status with step: "verify_email", and verification, resend and logout remain available. Refreshing or retrying the protected operation cannot bypass this requirement. Fetch the full profile after successful verification.

method_disabled also applies when an outstanding password reset/setup token, OAuth callback or signup invitation is completed after its method/path was disabled. Optional 2FA email confirmations use two_factor_code_invalid for an invalid, expired, wrong-session or wrong-action proof.

Email-change errors

• email_change_disabled (403): the optional capability is disabled.
• email_change_unavailable (409): unchanged or unavailable target address; occupancy is checked only after both mailbox proofs.
• email_change_invalid (400): incorrect codes, consumed/cancelled/replaced request, wrong initiating session/context, or exhausted guesses.
• email_change_expired (410): expiry or a request predating OTP pepper rotation.

Existing authentication, verification and MFA failures remain applicable. Wrong passwords return invalid_credentials (401); limits return rate_limit_exceeded (429); proof-email delivery failures return email_failed (500). Infrastructure failures retain the generic internal_error envelope. Completion-notice failures are retried outside the successful transaction.

Redis infrastructure failures

Redis snapshot failures fall back to authoritative SQL. Rate-limit backend failures retain 429 rate_limit_error and Retry-After: 60; exhausted budgets return rate_limit_exceeded. Notification counter failures never change login authorization. Canceled HTTP requests stop before downstream execution. Redis does not add a credential error code.