From c3084830637013a07da4c02e3275d86ba2ff1fca Mon Sep 17 00:00:00 2001
From: Hongwei <hongwei@tesobe.com>
Date: Wed, 28 Oct 2026 19:39:53 +0100
Subject: [PATCH] fix: keep Opey's status on session refusal and stop retrying
 it

The /backend/opey/auth route now passes on a 4xx answer from Opey instead of turning it into a 500, and names the cause (missing credentials, consent not ACCEPTED). The chat widget does not call the route for a logged-out visitor, does not retry a 4xx, and a consent that is still INITIATED is reported instead of being replaced by a new one.
---
 .../shared/src/lib/components/OpeyChat.svelte |  37 +---
 .../lib/opey/controllers/SessionController.ts |  51 ++++-
 packages/shared/src/lib/opey/errors.ts        |  40 ++++
 .../src/lib/opey/opeyAuthStatus.test.ts       | 196 ++++++++++++++++++
 .../lib/opey/services/OpeySessionService.ts   |  15 +-
 .../shared/src/lib/opey/state/SessionState.ts |  10 +-
 .../lib/server/obp/OBPIntegrationService.ts   |  37 ++++
 .../shared/src/lib/server/opey/handlers.ts    |  25 ++-
 8 files changed, 371 insertions(+), 40 deletions(-)
 create mode 100644 packages/shared/src/lib/opey/errors.ts
 create mode 100644 packages/shared/src/lib/opey/opeyAuthStatus.test.ts

diff --git a/packages/shared/src/lib/components/OpeyChat.svelte b/packages/shared/src/lib/components/OpeyChat.svelte
index fdc34667..53ca72b0 100644
--- a/packages/shared/src/lib/components/OpeyChat.svelte
+++ b/packages/shared/src/lib/components/OpeyChat.svelte
@@ -523,37 +523,10 @@
 		await sessionController.init();
 	}
 
-	// Add retry logic with exponential backoff
+	// Retry with backoff lives in the controller: a logged-out visitor makes no request, and a
+	// refusal such as 401 is reported once with its cause instead of being retried.
 	async function initializeOpeySessionWithRetry(maxRetries = 3, baseDelay = 1000) {
-		let lastError: string | null = null;
-		for (let attempt = 1; attempt <= maxRetries; attempt++) {
-			try {
-				await initializeOpeySession();
-				if (session.status === 'ready') {
-					logger.debug(`Opey session initialized successfully on attempt ${attempt}`);
-					return;
-				}
-				// Init didn't throw but the session isn't ready — capture whatever
-				// session.error was set to internally so it isn't swallowed.
-				if (session.error) lastError = session.error;
-			} catch (error) {
-				lastError = error instanceof Error ? error.message : String(error);
-				logger.warn(`Session initialization attempt ${attempt} failed:`, error);
-			}
-
-			if (attempt < maxRetries) {
-				const delay = baseDelay * Math.pow(2, attempt - 1); // Exponential backoff
-				logger.debug(`Retrying session initialization in ${delay}ms...`);
-				await new Promise((resolve) => setTimeout(resolve, delay));
-			}
-		}
-
-		// Surface the real underlying cause rather than just "after N attempts".
-		const finalMessage = lastError
-			? `Failed to initialize after ${maxRetries} attempts: ${lastError}`
-			: `Failed to initialize after ${maxRetries} attempts`;
-		logger.error(finalMessage);
-		sessionState.setStatus('error', finalMessage);
+		await sessionController.initWithRetry({ userAuthenticated, maxRetries, baseDelay });
 	}
 
 	/**
@@ -803,7 +776,7 @@
 				<button
 					class="text-s btn flex items-center rounded-lg border border-solid border-primary-500 bg-primary-50-950 px-3"
 					onclick={() => handleSendMessage(question.questionString)}
-					disabled={session?.status !== 'ready'}
+					disabled={session?.status !== 'ready' || !userAuthenticated}
 				>
 					{#if question.icon}
 						<question.icon />
@@ -1106,7 +1079,7 @@
 					: 'Ask me anything...'}
 			class="w-full resize-none border-none bg-transparent p-0.5 outline-none shadow-none focus:outline-none focus:shadow-none focus:ring-0 focus-visible:outline-none max-h-40 overflow-y-auto"
 			style="min-height: 2.5rem;"
-			disabled={session?.status !== 'ready'}
+			disabled={session?.status !== 'ready' || !userAuthenticated}
 			onkeydown={handleKeyPress}
 			oninput={autoResize}
 			rows="1"
diff --git a/packages/shared/src/lib/opey/controllers/SessionController.ts b/packages/shared/src/lib/opey/controllers/SessionController.ts
index b10c1de2..d27729a5 100644
--- a/packages/shared/src/lib/opey/controllers/SessionController.ts
+++ b/packages/shared/src/lib/opey/controllers/SessionController.ts
@@ -19,6 +19,7 @@ import { createLogger } from '../../utils/logger.js';
 const logger = createLogger('SessionController');
 import type { SessionService } from '../services/SessionService.js';
 import type { SessionState } from '../state/SessionState.js';
+import { isRetryableStatus } from '../errors.js';
 
 export class SessionController {
 	constructor(
@@ -34,10 +35,58 @@ export class SessionController {
 			this.sessionState.setStatus('ready');
 		} catch (error: any) {
 			logger.error('Session init error:', error);
-			this.sessionState.setStatus('error', error.message);
+			this.sessionState.setStatus('error', error.message, error.status);
 		}
 	}
 
+	/**
+	 * Start the session, retrying with exponential backoff.
+	 *
+	 * A logged-out visitor has nothing to authenticate with, so the auth route is not called at all
+	 * (the chat asks them to log in). A refusal that will come out the same next time (a 4xx such as
+	 * 401) is reported at once with its real cause instead of being retried.
+	 */
+	async initWithRetry(options: {
+		userAuthenticated: boolean;
+		maxRetries?: number;
+		baseDelay?: number;
+		sleep?: (ms: number) => Promise<void>;
+	}): Promise<void> {
+		const { userAuthenticated, maxRetries = 3, baseDelay = 1000 } = options;
+		const sleep = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+
+		if (!userAuthenticated) {
+			this.sessionState.setAuth(false);
+			this.sessionState.setStatus('ready');
+			return;
+		}
+
+		let lastError: string | undefined;
+		for (let attempt = 1; attempt <= maxRetries; attempt++) {
+			await this.init();
+			const snapshot = this.sessionState.current;
+			if (snapshot.status === 'ready') {
+				logger.debug(`Opey session initialized successfully on attempt ${attempt}`);
+				return;
+			}
+			lastError = snapshot.error;
+			if (!isRetryableStatus(snapshot.errorStatus)) {
+				// Leave the refusal as it is: its message names the cause.
+				logger.warn(`Opey session refused (HTTP ${snapshot.errorStatus}): ${lastError}`);
+				return;
+			}
+			if (attempt < maxRetries) {
+				await sleep(baseDelay * Math.pow(2, attempt - 1));
+			}
+		}
+
+		const finalMessage = lastError
+			? `Failed to initialize after ${maxRetries} attempts: ${lastError}`
+			: `Failed to initialize after ${maxRetries} attempts`;
+		logger.error(finalMessage);
+		this.sessionState.setStatus('error', finalMessage);
+	}
+
 	async destroy(): Promise<void> {
 		this.sessionState.setStatus('loading');
 		await this.service.deleteSession();
diff --git a/packages/shared/src/lib/opey/errors.ts b/packages/shared/src/lib/opey/errors.ts
new file mode 100644
index 00000000..ec17c5ad
--- /dev/null
+++ b/packages/shared/src/lib/opey/errors.ts
@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2025-2026 TESOBE GmbH
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/** A refusal while starting an Opey session; `statusCode` is what the auth route answers with. */
+export class OpeyAuthError extends Error {
+	statusCode: number;
+
+	constructor(message: string, statusCode: number) {
+		super(message);
+		this.name = 'OpeyAuthError';
+		this.statusCode = statusCode;
+	}
+}
+
+/** The status the auth route returns for an Opey answer: a client error is passed on, anything else is a bad gateway. */
+export function statusForOpeyAnswer(opeyStatus: number): number {
+	return opeyStatus >= 400 && opeyStatus < 500 ? opeyStatus : 502;
+}
+
+/** A 4xx other than request timeout / rate limit will answer the same way next time, so it is not retried. */
+export function isRetryableStatus(status: number | undefined): boolean {
+	if (status === undefined) return true;
+	if (status === 408 || status === 429) return true;
+	return !(status >= 400 && status < 500);
+}
diff --git a/packages/shared/src/lib/opey/opeyAuthStatus.test.ts b/packages/shared/src/lib/opey/opeyAuthStatus.test.ts
new file mode 100644
index 00000000..c0e8c172
--- /dev/null
+++ b/packages/shared/src/lib/opey/opeyAuthStatus.test.ts
@@ -0,0 +1,196 @@
+/*
+ * Copyright (C) 2025-2026 TESOBE GmbH
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Opey session start-up: the auth route keeps Opey's status, the widget does not retry a refusal
+ * or call the route for a logged-out visitor, and a consent that is still INITIATED is not
+ * replaced by a new one. Lives outside src/lib/server so vitest picks it up.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createOpeyAuthHandler } from '../server/opey/handlers';
+import { DefaultOBPIntegrationService } from '../server/obp/OBPIntegrationService';
+import { OpeySessionService } from './services/OpeySessionService';
+import { SessionController } from './controllers/SessionController';
+import { SessionState } from './state/SessionState';
+
+const OPEY = 'http://opey.test';
+
+function opeyRefuses(status: number, detail: string) {
+	return vi.fn(async () => new Response(JSON.stringify({ detail }), { status }));
+}
+
+function authEvent() {
+	return { request: new Request('http://app.test/backend/opey/auth', { method: 'POST' }) } as any;
+}
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+describe('POST /backend/opey/auth keeps the status Opey answered with', () => {
+	it('answers 401, not 500, to a logged-out visitor when Opey wants credentials', async () => {
+		vi.stubGlobal('fetch', opeyRefuses(401, 'Missing Authorization headers'));
+		const { POST } = createOpeyAuthHandler({
+			opeyBaseUrl: OPEY,
+			getAccessToken: () => undefined,
+			getSession: () => undefined
+		});
+		const res = await POST(authEvent());
+		expect(res.status).toBe(401);
+		expect((await res.json()).message).toContain('Missing Authorization headers');
+	});
+
+	it('answers 401, not 500, when Opey says the consent is not ACCEPTED', async () => {
+		vi.stubGlobal('fetch', opeyRefuses(401, 'OBP-35005: Consent-Id is not in status ACCEPTED'));
+		const { POST } = createOpeyAuthHandler({
+			opeyBaseUrl: OPEY,
+			opeyConsumerId: 'opey-consumer',
+			getAccessToken: () => 'token',
+			getSession: () => ({}),
+			getOrCreateOpeyConsent: async () => ({ consent_id: 'c1', jwt: 'a.b.c' }) as any
+		});
+		const res = await POST(authEvent());
+		expect(res.status).toBe(401);
+		expect((await res.json()).message).toContain('OBP-35005');
+	});
+
+	it('does not blame an expired JWT when the cause is the consent status', async () => {
+		vi.stubGlobal('fetch', opeyRefuses(401, 'OBP-35005: Consent-Id is not in status ACCEPTED'));
+		const info = vi.spyOn(console, 'info').mockImplementation(() => {});
+		const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+		const { POST } = createOpeyAuthHandler({
+			opeyBaseUrl: OPEY,
+			opeyConsumerId: 'opey-consumer',
+			getAccessToken: () => 'token',
+			getSession: () => ({}),
+			getOrCreateOpeyConsent: async () => ({ consent_id: 'c1', jwt: 'a.b.c' }) as any
+		});
+		await POST(authEvent());
+		const logged = [...info.mock.calls, ...log.mock.calls].flat().join(' ');
+		expect(logged).not.toContain('JWT expired');
+	});
+});
+
+describe('the widget session start-up', () => {
+	function controllerFor(createSession: () => Promise<{ authenticated: boolean }>) {
+		const state = new SessionState();
+		const service = { createSession: vi.fn(createSession) } as any;
+		return { state, service, controller: new SessionController(service, state) };
+	}
+
+	it('does not call the route for a logged-out visitor', async () => {
+		const { service, controller, state } = controllerFor(async () => ({ authenticated: false }));
+		await controller.initWithRetry({ userAuthenticated: false, sleep: async () => {} });
+		expect(service.createSession).not.toHaveBeenCalled();
+		expect(state.current.isAuthenticated).toBe(false);
+	});
+
+	it('does not retry a 401 and reports the real cause', async () => {
+		const { service, controller, state } = controllerFor(async () => {
+			const err: any = new Error('OBP-35005: Consent-Id is not in status ACCEPTED');
+			err.status = 401;
+			throw err;
+		});
+		await controller.initWithRetry({ userAuthenticated: true, sleep: async () => {} });
+		expect(service.createSession).toHaveBeenCalledTimes(1);
+		expect(state.current.status).toBe('error');
+		expect(state.current.error).toContain('OBP-35005');
+		expect(state.current.error).not.toContain('attempts');
+	});
+
+	it('still retries a server error', async () => {
+		const { service, controller } = controllerFor(async () => {
+			const err: any = new Error('boom');
+			err.status = 502;
+			throw err;
+		});
+		await controller.initWithRetry({
+			userAuthenticated: true,
+			maxRetries: 3,
+			sleep: async () => {}
+		});
+		expect(service.createSession).toHaveBeenCalledTimes(3);
+	});
+
+	it('OpeySessionService carries the HTTP status on the error it throws', async () => {
+		vi.stubGlobal(
+			'fetch',
+			vi.fn(
+				async () => new Response(JSON.stringify({ message: 'nope', code: 401 }), { status: 401 })
+			)
+		);
+		await expect(
+			new OpeySessionService('/backend/opey/auth').createSession()
+		).rejects.toMatchObject({
+			status: 401,
+			message: 'nope'
+		});
+	});
+});
+
+describe('getOrCreateOpeyConsent with a consent that is not ACCEPTED', () => {
+	const session: any = { data: { oauth: { access_token: 'tok' } } };
+	const jwt = 'x.eyJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1In0.y';
+
+	function obpWith(consents: any[], created?: any) {
+		const post = vi.fn(async () => created);
+		const get = vi.fn(async (path: string) => {
+			if (path.endsWith('/my/consents')) return { consents };
+			throw new Error('not found');
+		});
+		return {
+			post,
+			get,
+			svc: new DefaultOBPIntegrationService('opey-consumer', { get, post } as any)
+		};
+	}
+
+	it('does not create another consent while one is INITIATED', async () => {
+		const { post, svc } = obpWith([
+			{
+				consent_id: 'c1',
+				consumer_id: 'opey-consumer',
+				status: 'INITIATED',
+				jwt,
+				jwt_expires_at: new Date(Date.now() + 3600_000).toISOString()
+			}
+		]);
+		await expect(svc.getOrCreateOpeyConsent(session)).rejects.toMatchObject({ statusCode: 401 });
+		expect(post).not.toHaveBeenCalled();
+	});
+
+	it('reports a freshly created consent that comes back INITIATED instead of handing it to Opey', async () => {
+		const { post, svc } = obpWith([], { consent_id: 'c2', status: 'INITIATED', jwt });
+		await expect(svc.getOrCreateOpeyConsent(session)).rejects.toMatchObject({ statusCode: 401 });
+		expect(post).toHaveBeenCalledTimes(1);
+	});
+
+	it('still returns an ACCEPTED consent from the list without creating one', async () => {
+		const { post, svc } = obpWith([
+			{
+				consent_id: 'c3',
+				consumer_id: 'opey-consumer',
+				status: 'ACCEPTED',
+				jwt,
+				jwt_expires_at: new Date(Date.now() + 3600_000).toISOString()
+			}
+		]);
+		const consent = await svc.getOrCreateOpeyConsent(session);
+		expect(consent.consent_id).toBe('c3');
+		expect(post).not.toHaveBeenCalled();
+	});
+});
diff --git a/packages/shared/src/lib/opey/services/OpeySessionService.ts b/packages/shared/src/lib/opey/services/OpeySessionService.ts
index beab7f12..7d82fdfb 100644
--- a/packages/shared/src/lib/opey/services/OpeySessionService.ts
+++ b/packages/shared/src/lib/opey/services/OpeySessionService.ts
@@ -31,6 +31,17 @@ import type { SessionService } from './SessionService.js';
  * the host app's server route, which is the only place that has
  * access to the OAuth token.
  */
+/** Session start-up refused by the auth route; `status` is its HTTP status. */
+export class OpeySessionError extends Error {
+	status: number;
+
+	constructor(message: string, status: number) {
+		super(message);
+		this.name = 'OpeySessionError';
+		this.status = status;
+	}
+}
+
 export class OpeySessionService implements SessionService {
 	constructor(private authEndpoint: string = '/backend/opey/auth') {}
 
@@ -42,10 +53,10 @@ export class OpeySessionService implements SessionService {
 			credentials: 'include'
 		});
 
-		const data = await response.json();
+		const data = await response.json().catch(() => ({}));
 
 		if (!response.ok) {
-			throw new Error(data.message ?? `HTTP ${response.status}`);
+			throw new OpeySessionError(data.message ?? `HTTP ${response.status}`, response.status);
 		}
 
 		logger.info(`Opey session created - authenticated: ${data.authenticated}`);
diff --git a/packages/shared/src/lib/opey/state/SessionState.ts b/packages/shared/src/lib/opey/state/SessionState.ts
index ca1cea29..5d1e7756 100644
--- a/packages/shared/src/lib/opey/state/SessionState.ts
+++ b/packages/shared/src/lib/opey/state/SessionState.ts
@@ -19,6 +19,8 @@ export interface SessionSnapshot {
     isAuthenticated: boolean;
     status: 'ready' | 'loading' | 'error';
     error?: string;
+    /** HTTP status of the refusal that put the session into 'error', if it came from the server. */
+    errorStatus?: number;
 }
 
 
@@ -34,6 +36,10 @@ export class SessionState {
     }
     private subscribers: Array<(snapshot: SessionSnapshot) => void> = [];
 
+    get current(): SessionSnapshot {
+        return this.snapshot;
+    }
+
     subscribe(fn: (snapshot: SessionSnapshot) => void): () => void {
         this.subscribers.push(fn);
         fn(this.snapshot);
@@ -48,8 +54,8 @@ export class SessionState {
         this.emit();
     }
 
-    setStatus(status: SessionSnapshot['status'], error?: string) {
-        this.snapshot = { ...this.snapshot, status, error}
+    setStatus(status: SessionSnapshot['status'], error?: string, errorStatus?: number) {
+        this.snapshot = { ...this.snapshot, status, error, errorStatus}
         this.emit();
     }
 
diff --git a/packages/shared/src/lib/server/obp/OBPIntegrationService.ts b/packages/shared/src/lib/server/obp/OBPIntegrationService.ts
index f4946880..e615b06f 100644
--- a/packages/shared/src/lib/server/obp/OBPIntegrationService.ts
+++ b/packages/shared/src/lib/server/obp/OBPIntegrationService.ts
@@ -22,6 +22,7 @@ import type { Session } from 'svelte-kit-sessions';
 import type { OBPRequests } from '$shared/obp/requests';
 import type { OBPConsent, OBPConsentInfo } from '$shared/obp/types';
 import { capConsentTtlSeconds } from './consentsConfig.js';
+import { OpeyAuthError } from '$shared/opey/errors';
 
 export interface OBPIntegrationService {
   getOrCreateOpeyConsent(session: Session): Promise<OBPConsent>;
@@ -52,8 +53,18 @@ export class DefaultOBPIntegrationService implements OBPIntegrationService {
       return existingConsentId;
     }
 
+    // A consent created earlier that is still waiting (INITIATED) will not become usable by creating
+    // another one; every extra consent is one more the user has to deal with.
+    const pending = await this.findPendingOpeyConsent(session.data.oauth.access_token);
+    if (pending) {
+      throw this.consentNotAccepted(pending);
+    }
+
     // Create new consent
     const consent = await this.createImplicitConsent(session.data.oauth.access_token);
+    if (consent.status && consent.status !== 'ACCEPTED') {
+      throw this.consentNotAccepted(consent);
+    }
     const userIdentifier = extractUsernameFromJWT(consent.jwt);
     logger.info(`getOrCreateOpeyConsent says: Created new consent JWT - Primary user: ${userIdentifier}`);
     return consent;
@@ -129,6 +140,32 @@ export class DefaultOBPIntegrationService implements OBPIntegrationService {
 		}
 	}
 
+  private consentNotAccepted(consent: { consent_id?: string; status?: string }): OpeyAuthError {
+    return new OpeyAuthError(
+      `Opey consent ${consent.consent_id ?? ''} is in status ${consent.status}, not ACCEPTED: it has to be accepted before the chat can use it`,
+      401
+    );
+  }
+
+  /** The Opey consent of this user that was created but not accepted yet and has not expired. */
+  private async findPendingOpeyConsent(accessToken: string): Promise<OBPConsent | null> {
+    try {
+      const response = await this.obpRequests.get('/obp/v5.1.0/my/consents', accessToken);
+      const consents: OBPConsent[] = response.consents || [];
+      return (
+        consents.find(
+          (c) =>
+            c.consumer_id === this.opeyConsumerId &&
+            c.status === 'INITIATED' &&
+            !(c.jwt_expires_at && this.isConsentExpired(c))
+        ) ?? null
+      );
+    } catch (error) {
+      logger.info('findPendingOpeyConsent says: consent listing failed:', error);
+      return null;
+    }
+  }
+
 	private async createImplicitConsent(accessToken: string): Promise<OBPConsent> {
 		const now = new Date().toISOString().split('.')[0] + 'Z';
 
diff --git a/packages/shared/src/lib/server/opey/handlers.ts b/packages/shared/src/lib/server/opey/handlers.ts
index ce2e7506..79338c73 100644
--- a/packages/shared/src/lib/server/opey/handlers.ts
+++ b/packages/shared/src/lib/server/opey/handlers.ts
@@ -21,6 +21,7 @@ import { createLogger } from '../../utils/logger.js';
 import { extractUsernameFromJWT } from '../../utils/jwt.js';
 import { obpErrorResponse } from '../../obp/errors.js';
 import type { OBPConsent } from '../../obp/types.js';
+import { OpeyAuthError, statusForOpeyAnswer } from '../../opey/errors.js';
 
 const logger = createLogger('OpeyAuthHandler');
 
@@ -37,6 +38,18 @@ export interface OpeyAuthHandlerConfig {
 	getOrCreateOpeyConsent?: (session: any) => Promise<OBPConsent>;
 }
 
+/** Opey answers errors as `{"detail": "..."}`; fall back to the raw text. */
+function opeyDetail(errorText: string): string {
+	try {
+		const parsed = JSON.parse(errorText);
+		if (typeof parsed?.detail === 'string') return parsed.detail;
+		if (typeof parsed?.message === 'string') return parsed.message;
+	} catch {
+		// not JSON
+	}
+	return errorText;
+}
+
 export function createOpeyAuthHandler(config: OpeyAuthHandlerConfig): {
 	POST: RequestHandler;
 } {
@@ -55,7 +68,10 @@ export function createOpeyAuthHandler(config: OpeyAuthHandlerConfig): {
 		if (!opeyResponse.ok) {
 			const errorText = await opeyResponse.text();
 			logger.error(`Failed to create anonymous Opey session - Error: ${errorText}`);
-			throw new Error(`Failed to create anonymous Opey session: ${errorText}`);
+			throw new OpeyAuthError(
+				`Failed to create anonymous Opey session: ${opeyDetail(errorText)}`,
+				statusForOpeyAnswer(opeyResponse.status)
+			);
 		}
 
 		logger.info('Successfully created anonymous Opey session');
@@ -104,7 +120,10 @@ export function createOpeyAuthHandler(config: OpeyAuthHandlerConfig): {
 			logger.error(
 				`Failed to create authenticated Opey session - Primary user: ${userIdentifier} - Error: ${errorText}`
 			);
-			throw new Error(`Failed to create authenticated Opey session: ${errorText}`);
+			throw new OpeyAuthError(
+				`Failed to create authenticated Opey session: ${opeyDetail(errorText)}`,
+				statusForOpeyAnswer(opeyResponse.status)
+			);
 		}
 
 		logger.info(
@@ -137,7 +156,7 @@ export function createOpeyAuthHandler(config: OpeyAuthHandlerConfig): {
 			try {
 				return await getAuthenticatedSession(portalSession);
 			} catch (error: unknown) {
-				logger.info('JWT expired for Opey session - user needs to re-authenticate:', error);
+				logger.info('Opey session could not be created for the logged-in user:', error);
 				const { body, status } = obpErrorResponse(error);
 				return json(body, { status });
 			}