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/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.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.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 createAuthHandlers and the Fastify 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 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_)

CodeStatusDefault messageRaised when and what to do
OIDC_001502Identity provider discovery failedDiscovery 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_002400Invalid authorization responseThe 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_003502Token request failedThe 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_004501The identity provider does not support this operationlogoutUrl, revoke or introspect was called but the provider advertises no 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 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_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 Bearer <token>.
TOK_004403Insufficient scoperequireScopes 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. 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_002502Unexpected response from auth-serviceThe 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_)

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.topupUrl().
GW_002429The gateway rate limit was reachedThe gateway answered 429. details.retryAfterSeconds carries Retry-After when present. 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. 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 onError as the cause.
SES_003500Sign-in could not be completedThe 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_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 onError, 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 onError: look in your logs.

details keys

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

KeySet byMeaning
oauthErrorOIDC_002, OIDC_003The OAuth error code of the provider.
statusOIDC_003, API_001, GW_*, browser errorsAn HTTP status.
descriptionOIDC_003The provider's error_description.
reasonTOK_001, OIDC_002A jose or openid-client error code.
missingTOK_004Space-separated missing scopes.
scopeTOK_004The machine scope the provider refused.
apiCodeAPI_001The auth-service error code.
typeGW_*The error type reported by the gateway.
retryAfterSecondsGW_002Seconds to wait, from Retry-After.
Copyright © 2026