Error codes
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.messageanderr.detailsare 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
AuthHandlersand the Starlette adapter answer when the error escapes a route. Your own routes choose their own status.
Configuration (CFG_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
CFG_001 | 500 | Invalid SDK configuration | A 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_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
OIDC_001 | 502 | Identity provider discovery failed | Discovery 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_002 | 400 | Invalid authorization response | The 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_003 | 502 | Token request failed | The 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_004 | 501 | The identity provider does not support this operation | fetch_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_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
TOK_001 | 401 | Token verification failed | A 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_002 | 401 | No usable grant for this user: sign in again | The 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_003 | 401 | Missing or malformed bearer credentials | The Authorization header is absent or is not a bearer header. |
TOK_004 | 403 | Insufficient scope | require_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_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
API_001 | 502 | auth-service rejected the request | Wallet, 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_002 | 502 | Unexpected response from auth-service | The 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_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
GW_001 | 402 | Insufficient credit: the wallet cannot pay for this call | The gateway answered 402. Send the user to wallet.topup_url(). |
GW_002 | 429 | The gateway rate limit was reached | The gateway answered 429. details["retryAfterSeconds"] carries Retry-After when it is a non-negative number. Back off. |
GW_003 | 403 | The gateway refused the credentials or the resource | The 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_004 | 503 | The gateway is temporarily unavailable | The gateway answered 503, or could not be reached. Retry later. |
GW_005 | 502 | Unexpected response from the gateway | Any other status, or a listing in an unexpected shape. details["status"] and details["type"] carry what the gateway reported. |
Browser sessions (SES_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
SES_001 | 401 | Not signed in | No session, a forged cookie or an expired session. Redirect to the sign-in. |
SES_002 | 400 | The sign-in attempt is missing, expired or was tampered with | The 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_003 | 500 | Sign-in could not be completed | The 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_004 | 403 | Cross-origin request refused | POST /auth/logout came from another site. |
SES_005 | 403 | Sign-in failed | The 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_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
REQ_001 | 400 | Invalid request | A 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_)
| Code | Status | Default message | Raised when and what to do |
|---|---|---|---|
SRV_001 | 500 | Internal error | An 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:
| Key | Set by | Meaning |
|---|---|---|
oauthError | OIDC_002, OIDC_003 | The OAuth error code of the provider. |
status | OIDC_003, API_001, GW_* | An HTTP status. |
description | OIDC_003 | The provider's error_description. |
reason | TOK_001, OIDC_002 | A joserfc error code, or one of the OIDC_002 reasons above. |
missing | TOK_004 | Space-separated missing scopes. |
scope | TOK_004 | The machine scope the provider refused. |
apiCode | API_001 | The auth-service error code. |
type | GW_* | The error.type the gateway reported. |
retryAfterSeconds | GW_002 | The 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.