Errors

The SDK uses a hierarchy of typed error classes. Catch specific classes to handle different failure modes distinctly.

Error Hierarchy

text

Error
└── ThunderIDError
    ├── ThunderIDAPIError
    └── ThunderIDRuntimeError
ThunderIDAuthException  (separate — thrown by auth flow internals)
└── InvalidLogoutTokenError

ThunderIDError

Base class for all SDK errors. Extends native Error.

ts

import { ThunderIDError } from '@thunderid/javascript'

try {
  await client.initialize(config)
} catch (err) {
  if (err instanceof ThunderIDError) {
    console.error(err.code, err.origin, err.message)
  }
}

Constructor

ts

new ThunderIDError(message: string, code: string, origin: string)

Parameter	Type	Description
message	string	Human-readable error description
code	string	Machine-readable error code (e.g., 'JS-AUTH_CORE-RAT1-NF01')
origin	string	The function or component that originated the error

Properties

Property	Type	Description
message	string	Human-readable description
code	string	Machine-readable error code
origin	string	Originating function name

ThunderIDAPIError

Thrown when the ThunderID REST API returns an error response (4xx or 5xx).

ts

import { ThunderIDAPIError } from '@thunderid/javascript'

try {
  await getOrganization({ baseUrl, organizationId: 'bad-id', ... })
} catch (err) {
  if (err instanceof ThunderIDAPIError) {
    console.error(err.statusCode, err.statusText)
  }
}

Constructor

ts

new ThunderIDAPIError(
  message: string,
  code: string,
  origin: string,
  statusCode?: number,
  statusText?: string,
  prefix?: string,
)

Properties (Extends ThunderIDError)

Property	Type	Description
statusCode	number	HTTP status code of the API response
statusText	string	HTTP status text (e.g., 'Not Found', 'Unauthorized')

ThunderIDRuntimeError

Thrown when an error occurs during SDK runtime operations unrelated to the API (e.g., storage failures, configuration errors).

ts

import { ThunderIDRuntimeError } from '@thunderid/javascript'

try {
  client.clearSession()
} catch (err) {
  if (err instanceof ThunderIDRuntimeError) {
    console.error(err.details)
  }
}

Constructor

ts

new ThunderIDRuntimeError(
  message: string,
  code: string,
  origin: string,
  details?: unknown,
)

Properties (Extends ThunderIDError)

Property	Type	Description
details	unknown	Additional context about the error (original exception, state dump, etc.)

ThunderIDAuthException

Thrown by the core authentication flow methods within ThunderIDJavaScriptClient (e.g., getSignInUrl(), requestAccessToken(), getSignOutUrl()). Not a subclass of ThunderIDError.

ts

import { ThunderIDAuthException } from '@thunderid/javascript'

try {
  await client.signIn()
} catch (err) {
  if (err instanceof ThunderIDAuthException) {
    console.error('Auth failed:', err.message)
  }
}

Error Codes

Auth exception codes follow the pattern JS-AUTH_CORE-<OPERATION>-<TYPE><INDEX>:

Suffix	Meaning
-NF01	Not found (missing endpoint or parameter)
-NE02	Network error (fetch failed)
-HE03	HTTP error (non-2xx response)
-IV02	Invalid (resolution or parsing failure)

InvalidLogoutTokenError

Thrown by handleBackchannelLogout() in the Node SDK when a back-channel logout token is not valid or its jti was already handled. Extends ThunderIDAuthException, and its code names the check that failed. A logout handler answers 400 for it and a 5xx for any other error, so ThunderID retries only when a retry can help. See handleBackchannelLogout(logoutToken).

ts

import { InvalidLogoutTokenError } from '@thunderid/node'

try {
  await client.handleBackchannelLogout(logoutToken)
} catch (err) {
  if (err instanceof InvalidLogoutTokenError) {
    console.error('Rejected logout token:', err.code)
  }
}

Catching All SDK Errors

ts

import {
  ThunderIDError,
  ThunderIDAPIError,
  ThunderIDRuntimeError,
  ThunderIDAuthException,
} from '@thunderid/javascript'

try {
  await client.signIn()
} catch (err) {
  if (err instanceof ThunderIDAPIError) {
    // Handle API-level errors (HTTP 4xx/5xx from ThunderID)
    console.error(`API error ${err.statusCode}: ${err.message}`)
  } else if (err instanceof ThunderIDAuthException) {
    // Handle auth flow errors (PKCE, token exchange, endpoint resolution)
    console.error(`Auth error [${err.message}]`)
  } else if (err instanceof ThunderIDRuntimeError) {
    // Handle runtime/internal errors
    console.error(`Runtime error: ${err.message}`, err.details)
  } else if (err instanceof ThunderIDError) {
    // Catch-all for any other SDK error
    console.error(`SDK error [${err.code}]: ${err.message}`)
  } else {
    throw err  // Re-throw unexpected errors
  }
}