CIRCLE
Reference

Error codes

Every error code of the SDK registry with its meaning, the HTTP status the web handlers answer, and what to do.

Every failure raised by the SDK is an AuthAiError with a stable code from the registry in src/auth_ai/errors.py. Codes are grouped by prefix, mirroring auth-service and the TypeScript SDK: CFG_ configuration, OIDC_ protocol exchanges with the provider, TOK_ token and grant handling, API_ calls to the auth-service REST API, GW_ calls to the LiteLLM gateway, SES_ browser sessions, REQ_ invalid requests to the SDK's own routes, SRV_ unexpected failures of the SDK's own handlers.

import logging

from auth_ai import AuthAiError

logger = logging.getLogger(__name__)


def report(err: AuthAiError) -> dict[str, str]:
    # Developer view, for logs: message and details.
    logger.error("auth error", extra={"error": err.to_json()})
    # User view, for responses: the code and a generic message.
    return err.to_public_json()
  • err.message and err.details are for logs. They may name a scope or carry a provider's description; they never carry tokens or secrets.
  • err.to_public_json() is what may reach a user. The web handlers answer with it, in the envelope { "error": { "code", "message" } }.
  • The HTTP status column is what AuthHandlers and the Starlette adapter answer when the error escapes a route. Your own routes choose their own status.

Configuration (CFG_)

CodeStatusDefault messageRaised when and what to do
CFG_001500Invalid SDK configurationA developer error, raised as early as possible: an invalid AuthClient configuration (the message lists each field), a base_path or redirect_uri mismatch, a cookie secret shorter than 32 characters, a machine API or client_credentials without client_secret, ai.for_user(...).gateway without gateway_url, a gateway request to another origin, an invalid MCP server name or consumption report, a bearer audience that is not a URL, an unsafe bearer_challenge value, an invalid cookie name or value. Fix the code or the configuration.

Protocol with the provider (OIDC_)

CodeStatusDefault messageRaised when and what to do
OIDC_001502Identity provider discovery failedDiscovery failed, the discovery document names another issuer, or the provider advertises no asymmetric ID token algorithm or no jwks_uri. Check issuer (HTTPS, no trailing slash, reachable). A failed discovery is retried on the next call.
OIDC_002400Invalid authorization responseThe callback carried an error, a repeated parameter, a bad iss or state, no code, or the token response had no ID token. details["oauthError"] holds the provider's error code, details["reason"] one of repeated_parameter, missing_iss, iss_mismatch, state_mismatch or missing_code. Surfaced to browsers as SES_005 by the sign-in handlers.
OIDC_003502Token request failedThe token endpoint rejected the request, was unreachable, or answered an unexpected shape. details holds oauthError, status and the provider's description. A 401 challenge means a wrong client_id or client_secret. Also raised when the response is not a bearer token or has no expires_in, when revocation or introspection is refused, and for UserInfo failures: an unreachable endpoint, a non-2xx answer, a non-JSON body, a non-object body, or a non-HTTPS userinfo_endpoint.
OIDC_004501The identity provider does not support this operationfetch_userinfo, logout_url, revoke or introspect was called but the provider advertises no userinfo_endpoint, end_session_endpoint, revocation_endpoint or introspection_endpoint.

Tokens and grants (TOK_)

CodeStatusDefault messageRaised when and what to do
TOK_001401Token verification failedA JWT failed verification (details["reason"] holds the joserfc error code), the provider's keys could not be fetched, the claims have an unexpected shape, the nonce does not match, an opaque token or a token not bound to a client reached BearerVerifier, a logout token was invalid or replayed, or a refresh returned no ID token or one that belongs to another user. The UserInfo sub mismatch (sign-in and claim renewal) also raises TOK_001.
TOK_002401No usable grant for this user: sign in againThe user has no grant, or the provider rejected it (invalid_grant), in which case the grant was dropped. Send the user through /auth/login.
TOK_003401Missing or malformed bearer credentialsThe Authorization header is absent or is not a bearer header.
TOK_004403Insufficient scoperequire_scopes found a missing scope (details["missing"]), or the application lacks a machine scope (details["scope"]): ask a superadmin to grant it.

auth-service REST API (API_)

CodeStatusDefault messageRaised when and what to do
API_001502auth-service rejected the requestWallet, billing or consumption call refused, or auth-service unreachable. details["status"] is the HTTP status and details["apiCode"] the auth-service error code when the body carried one (for example CONS_003). See the auth-service error codes.
API_002502Unexpected response from auth-serviceThe answer did not match the expected shape (or a consumption report answered success: false). Check that SDK and auth-service versions are compatible.

LiteLLM gateway (GW_)

CodeStatusDefault messageRaised when and what to do
GW_001402Insufficient credit: the wallet cannot pay for this callThe gateway answered 402. Send the user to wallet.topup_url().
GW_002429The gateway rate limit was reachedThe gateway answered 429. details["retryAfterSeconds"] carries Retry-After when it is a non-negative number. Back off.
GW_003403The gateway refused the credentials or the resourceThe gateway answered 401 or 403: for example a model the user's plan may not reach (auth-service documents team_model_access_denied), or a token the gateway does not accept.
GW_004503The gateway is temporarily unavailableThe gateway answered 503, or could not be reached. Retry later.
GW_005502Unexpected response from the gatewayAny other status, or a listing in an unexpected shape. details["status"] and details["type"] carry what the gateway reported.

Browser sessions (SES_)

CodeStatusDefault messageRaised when and what to do
SES_001401Not signed inNo session, a forged cookie or an expired session. Redirect to the sign-in.
SES_002400The sign-in attempt is missing, expired or was tampered withThe sealed handshake cookie is missing, expired, tampered or unreadable. Inside /auth/callback it becomes SES_005; the code reaches your on_error as the cause.
SES_003500Sign-in could not be completedThe ID token carries no sid while require_provider_session is on. Enable end-session or a back-channel logout URI in auth-service. Inside /auth/callback it becomes SES_005.
SES_004403Cross-origin request refusedPOST /auth/logout came from another site.
SES_005403Sign-in failedThe one answer to every failed callback. The real cause (SES_002, SES_003, OIDC_002, OIDC_003, TOK_001…) is passed to on_error, never to the browser.

Invalid requests (REQ_)

CodeStatusDefault messageRaised when and what to do
REQ_001400Invalid requestA request to one of the SDK's own routes carries an invalid parameter, for example a days outside 1 to 90 on /wallet/stats. Fix the caller.

Unexpected failures (SRV_)

CodeStatusDefault messageRaised when and what to do
SRV_001500Internal errorAn error that is not an AuthAiError escaped a route. It is passed to on_error: look in your logs.

details keys

details values are strings, numbers, booleans or None. The keys the SDK sets:

KeySet byMeaning
oauthErrorOIDC_002, OIDC_003The OAuth error code of the provider.
statusOIDC_003, API_001, GW_*An HTTP status.
descriptionOIDC_003The provider's error_description.
reasonTOK_001, OIDC_002A joserfc error code, or one of the OIDC_002 reasons above.
missingTOK_004Space-separated missing scopes.
scopeTOK_004The machine scope the provider refused.
apiCodeAPI_001The auth-service error code.
typeGW_*The error.type the gateway reported.
retryAfterSecondsGW_002The Retry-After value, in seconds.

Helpers

is_auth_ai_error_code(value) tells whether a string is a code of the registry, which is useful when you parse an error envelope from another service. The AuthAiErrorCode type is the Literal of every code.

Copyright © 2026