Error Handling

Overview

@authrim/core provides a structured error system with classification, severity levels, and recovery guidance. All SDK errors are instances of AuthrimError.

AuthrimError

import { AuthrimError } from '@authrim/core';

try {
  const tokens = await client.handleCallback(url);
} catch (error) {
  if (error instanceof AuthrimError) {
    console.log(error.code);     // e.g., 'invalid_state'
    console.log(error.message);  // Human-readable description
    console.log(error.details);  // Additional context (object)
    console.log(error.cause);    // Underlying error (if any)
    console.log(error.meta);     // Classification metadata
  }
}

AuthrimError Properties

Property	Type	Description
code	AuthrimErrorCode	Machine-readable error code
message	string	Human-readable error description
details	Record<string, unknown> | undefined	Additional context
cause	Error | undefined	Underlying error
meta	AuthrimErrorMeta | undefined	Classification metadata

Error Metadata

Each error includes metadata that guides recovery:

import { getErrorMeta } from '@authrim/core';

const meta = getErrorMeta(error);

console.log(meta.severity);     // 'fatal' | 'error' | 'warning'
console.log(meta.transient);    // Is this a temporary issue?
console.log(meta.retryable);    // Can this be retried?
console.log(meta.retryAfterMs); // Suggested wait before retry
console.log(meta.maxRetries);   // Max retry attempts
console.log(meta.userAction);   // What the user should do

AuthrimErrorMeta

Property	Type	Description
severity	'fatal' | 'error' | 'warning'	Error severity
transient	boolean	Whether the error is temporary
retryable	boolean	Whether the operation can be retried
retryAfterMs	number | undefined	Suggested delay before retry (ms)
maxRetries	number | undefined	Maximum retry attempts
userAction	string	Suggested user action

User Actions

Action	Description
'retry'	User can retry the operation
'reauthenticate'	User needs to log in again
'contact_support'	Unrecoverable error
'check_network'	Network connectivity issue
'none'	No user action required (SDK handles it)

Error Classification

Use classifyError() to categorize errors programmatically:

import { classifyError, isRetryableError } from '@authrim/core';

try {
  await client.token.getAccessToken();
} catch (error) {
  if (error instanceof AuthrimError) {
    const classification = classifyError(error);

    if (isRetryableError(error)) {
      // Retry the operation
    }
  }
}

Error Codes

OAuth / OIDC Errors

Code	Severity	Retryable	Description
oauth_error	error	No	Generic OAuth error
invalid_request	error	No	Malformed request
unauthorized_client	fatal	No	Client not authorized
access_denied	error	No	User denied access
invalid_scope	error	No	Invalid scope requested
server_error	error	Yes	Server error
temporarily_unavailable	error	Yes	Server temporarily unavailable
invalid_grant	error	No	Invalid authorization code or refresh token

State / PKCE Errors

Code	Severity	Retryable	Description
invalid_state	fatal	No	State mismatch (possible CSRF)
expired_state	error	No	State expired
nonce_mismatch	fatal	No	Nonce mismatch in ID token
missing_code	error	No	No authorization code in callback
missing_state	error	No	No state parameter in callback
missing_id_token	error	No	No ID token in response

Token Errors

Code	Severity	Retryable	Description
token_expired	error	No	Access token expired
token_error	error	Yes	Token operation failed
refresh_error	error	Yes	Token refresh failed
token_exchange_error	error	Yes	Token exchange failed
no_tokens	error	No	No tokens available

Network Errors

Code	Severity	Retryable	Description
network_error	error	Yes	Network request failed
timeout_error	error	Yes	Request timed out

Session Errors

Code	Severity	Retryable	Description
session_expired	error	No	Session has expired
login_required	error	No	User needs to log in
interaction_required	error	No	User interaction required
consent_required	error	No	User consent required
account_selection_required	error	No	Account selection required

Security Feature Errors

Code	Severity	Retryable	Description
par_error	error	Yes	PAR request failed
par_required	error	No	Server requires PAR
no_par_endpoint	error	No	PAR endpoint not available
dpop_key_generation_error	error	Yes	DPoP key generation failed
dpop_proof_generation_error	error	Yes	DPoP proof generation failed
jar_signing_error	error	No	JAR signing failed
jar_required	error	No	Server requires JAR
jarm_validation_error	error	No	JARM validation failed
jarm_signature_invalid	fatal	No	JARM signature invalid

Device Flow Errors

Code	Severity	Retryable	Description
device_authorization_error	error	Yes	Device authorization failed
device_authorization_expired	error	No	Device code expired
device_access_denied	error	No	User denied device authorization

System Errors

Code	Severity	Retryable	Description
not_initialized	fatal	No	Client not initialized
no_discovery	error	Yes	Discovery document not available

Retry Logic

The SDK provides built-in retry utilities:

withRetry()

Automatically retry a function with exponential backoff:

import { withRetry } from '@authrim/core';

const result = await withRetry(
  () => client.token.getAccessToken(),
  {
    maxRetries: 3,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
    backoffMultiplier: 2,
  },
);

RetryOptions

Parameter	Type	Default	Description
maxRetries	number	3	Maximum retry attempts
baseDelayMs	number	1000	Base delay in milliseconds
maxDelayMs	number	10000	Maximum delay in milliseconds
backoffMultiplier	number	2	Exponential backoff multiplier

calculateBackoffDelay()

Calculate the delay for a specific retry attempt:

import { calculateBackoffDelay } from '@authrim/core';

const delay = calculateBackoffDelay(attempt, baseMs);
// attempt 0: baseMs
// attempt 1: baseMs * 2
// attempt 2: baseMs * 4
// ...

createRetryFunction()

Create a reusable retry-wrapped function:

import { createRetryFunction } from '@authrim/core';

const getTokenWithRetry = createRetryFunction(
  () => client.token.getAccessToken(),
  { maxRetries: 3 },
);

const token = await getTokenWithRetry();

Error Event Integration

Errors are automatically emitted as events:

import { emitClassifiedError } from '@authrim/core';

// The SDK does this internally, but you can listen for the events:
client.on('error:fatal', (event) => {
  // Unrecoverable — redirect to login or show error page
  console.error('Fatal:', event.error.code);
});

client.on('error:recoverable', (event) => {
  // SDK may retry automatically
  console.warn('Recoverable:', event.error.code);
});

Practical Error Handling Patterns

Login Flow

try {
  const tokens = await client.handleCallback(url);
} catch (error) {
  if (!(error instanceof AuthrimError)) throw error;

  switch (error.code) {
    case 'invalid_state':
    case 'expired_state':
      // Security issue or timeout — restart login
      redirectToLogin();
      break;
    case 'access_denied':
      showMessage('You denied the login request.');
      break;
    case 'server_error':
    case 'temporarily_unavailable':
      showMessage('Server is temporarily unavailable. Please try again.');
      break;
    default:
      showMessage(`Login failed: ${error.message}`);
  }
}

API Calls

try {
  const token = await client.token.getAccessToken();
  const data = await callApi(token);
} catch (error) {
  if (!(error instanceof AuthrimError)) throw error;

  const meta = getErrorMeta(error);

  if (meta.userAction === 'reauthenticate') {
    redirectToLogin();
  } else if (meta.userAction === 'check_network') {
    showMessage('Please check your internet connection.');
  } else if (meta.retryable) {
    // Retry with backoff
    await withRetry(() => client.token.getAccessToken(), { maxRetries: 3 });
  }
}

Next Steps

• Events — Event system reference
• Token Management — Token lifecycle and refresh
• Configuration — Timeout and retry settings