Skip to main content

Auth Error Codes – API and Observability

This document summarizes the structured auth error codes exposed by the backend so ops, SREs, and observability pipelines can reason about failures without parsing free‑form messages.

All of these appear under the detail field of HTTP error responses as:

{
  "status": "error",
  "code": "<error_code>",
  "message": "<human_readable_summary>"
}

Login and Refresh​

  • auth_login_db_error

    • Route: POST /auth/login
    • Meaning: Database failure while loading user or RBAC data during login.
    • Action: Treat as 5xx; investigate DB health before retrying.

  • auth_login_internal_error

    • Route: POST /auth/login
    • Meaning: Unexpected server error during login that is not a DB error or explicit 4xx.
    • Action: Inspect logs for stack trace; treat as 5xx.

  • auth_refresh_db_error

    • Route: POST /auth/refresh
    • Meaning: Database failure while validating refresh token/session state.
    • Action: Treat as 5xx; user should re‑authenticate once underlying issue is resolved.

WebAuthn / SSO​

  • auth_webauthn_db_error

    • Route: POST /auth/webauthn/login/verify
    • Meaning: Database failure while resolving tenant or RBAC during WebAuthn login.
    • Action: Treat as 5xx; investigate DB and retry once healthy.

  • auth_webauthn_internal_error

    • Route: POST /auth/webauthn/login/verify
    • Meaning: Unexpected server error during WebAuthn login.
    • Action: Treat as 5xx; inspect logs for details.

  • auth_google_db_error

    • Route: POST /auth/login/google
    • Meaning: Database failure while resolving tenant or RBAC after Google OAuth.
    • Action: Treat as 5xx; investigate DB health.

  • auth_google_internal_error

    • Route: POST /auth/login/google
    • Meaning: Unexpected server error during Google OAuth login.
    • Action: Treat as 5xx; inspect logs for details.

API Keys​

  • auth_api_key_internal_error
    • Route: POST /auth/api-key
    • Meaning: Unexpected server error while generating an API key (e.g., JWT/cipher issues or internal failures).
    • Action: Treat as 5xx; inspect logs for details and ensure SECRET_KEY/JWT configuration is valid.