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/errors.ts. Codes are grouped by prefix, mirroring auth-service: 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, SRV_ unexpected failures of the SDK's own handlers.
import { AuthAiError } from "@circle-rd/auth-ai";
function report(err: unknown) {
if (!(err instanceof AuthAiError)) throw err;
// Developer view, for logs: message and details.
console.error(JSON.stringify(err.toJSON()));
// User view, for responses: the code and a generic message.
return err.toPublicJSON();
}
err.messageanderr.detailsare for logs. They may name a scope or carry a provider's description; they never carry tokens or secrets.err.toPublicJSON()is what may reach a user. The web handlers answer with it, in the envelope{ "error": { "code", "message" } }.- The HTTP status column is what
createAuthHandlersand the Fastify 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 createAuthClient config (the message lists each path), a basePath or redirectUri mismatch, a cookie secret shorter than 32 characters, a machine API or clientCredentials without clientSecret, ai.forUser(...).gateway without gatewayUrl, a gateway.fetch call to another origin, an invalid MCP server name or consumption report, a bearer audience that is not a URL, an unsafe bearerChallenge 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, 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 bad state, or no ID token. details.oauthError holds the provider's error code. Surfaced to browsers as SES_005 by the sign-in handlers. |
OIDC_003 | 502 | Token request failed | The token endpoint rejected the request. details holds oauthError, status and the provider's description. A 401 challenge means a wrong clientId or clientSecret. Also raised when the response has no expires_in, or when the UserInfo endpoint is unreachable or answers with an error status. |
OIDC_004 | 501 | The identity provider does not support this operation | logoutUrl, revoke or introspect was called but the provider advertises no 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 jose error code), its claims have an unexpected shape, the nonce does not match, an opaque token reached createBearerVerifier, a logout token was invalid or replayed, a refresh returned no ID token, or it belonged to another user. Also raised when a successful UserInfo response is unreadable or belongs to another user. |
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 Bearer <token>. |
TOK_004 | 403 | Insufficient scope | requireScopes 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. 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. In the browser client it also stands for an answer from your own backend that is not an error envelope. |
API_002 | 502 | Unexpected response from auth-service | The answer did not match the expected shape. In the browser client, the same for your backend's answer. 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.topupUrl(). |
GW_002 | 429 | The gateway rate limit was reached | The gateway answered 429. details.retryAfterSeconds carries Retry-After when present. 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. 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 onError as the cause. |
SES_003 | 500 | Sign-in could not be completed | The ID token carries no sid while requireProviderSession 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 onError, 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 onError: look in your logs. |
details keys
details values are strings, numbers, booleans or null. 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_*, browser errors | An HTTP status. |
description | OIDC_003 | The provider's error_description. |
reason | TOK_001, OIDC_002 | A jose or openid-client error code. |
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 reported by the gateway. |
retryAfterSeconds | GW_002 | Seconds to wait, from Retry-After. |