@@ -1,15 +1,11 @@
+import { apiFailure } from "../api/api-failure.js";
+
 export function reportApiErrorMessage(error: unknown, status: number): string {
-  return reportErrorMessage(typeof error === "object" && error !== null
-    ? { ...error, status }
-    : { status });
+  return reportErrorMessage(apiFailure(error, status));
 }
 
 export function reportErrorMessage(error: unknown): string {
-  const problem = typeof error === "object" && error !== null
-    ? error as { code?: unknown; status?: unknown }
-    : undefined;
-  const code = typeof problem?.code === "string" ? problem.code : undefined;
-  const status = problem?.status === undefined ? undefined : Number(problem.status);
+  const { code, status } = apiFailure(error);
 
   switch (code) {
     case "invalid_credentials":
 
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { apiFailure } from "./api-failure.js";
+
+describe("apiFailure", () => {
+  it("normalizes supported problem fields", () => {
+    expect(apiFailure({ code: "invalid_query", detail: "Unsupported dimension", status: "400" })).toEqual({
+      code: "invalid_query",
+      detail: "Unsupported dimension",
+      status: 400,
+    });
+  });
+
+  it("prefers the HTTP response status", () => {
+    expect(apiFailure({ status: 400 }, 404).status).toBe(404);
+  });
+
+  it("ignores malformed problem fields", () => {
+    expect(apiFailure({ code: 42, detail: "", status: "unknown" })).toEqual({
+      code: undefined,
+      detail: undefined,
+      status: undefined,
+    });
+  });
+});
@@ -0,0 +1,24 @@
+export interface ApiFailure {
+  code?: string;
+  detail?: string;
+  status?: number;
+}
+
+export function apiFailure(error: unknown, responseStatus?: number): ApiFailure {
+  const problem = typeof error === "object" && error !== null ? error as Record<string, unknown> : undefined;
+  return {
+    code: stringProperty(problem, "code"),
+    detail: stringProperty(problem, "detail"),
+    status: responseStatus ?? numberProperty(problem, "status"),
+  };
+}
+
+function stringProperty(value: Record<string, unknown> | undefined, property: string): string | undefined {
+  const candidate = value?.[property];
+  return typeof candidate === "string" && candidate.trim() ? candidate : undefined;
+}
+
+function numberProperty(value: Record<string, unknown> | undefined, property: string): number | undefined {
+  const candidate = Number(value?.[property]);
+  return Number.isFinite(candidate) ? candidate : undefined;
+}
@@ -21,7 +21,7 @@ import { createSettingsUpdate, validateConnection, validateEditableSettings } fr
 import { announceAnalyticsAvailability } from "../section/analytics-availability.js";
 import { MOCK_SCENARIOS, type MockScenarioDefinition } from "./mock-scenarios.js";
 import { identifierField, providerDescriptor, providerLogo } from "./provider-identity.js";
-import { settingsActionError, settingsLoadError, type SettingsLoadError } from "./settings-error.js";
+import { settingsError, type SettingsError } from "./settings-error.js";
 
 type NewConnection =
   | { kind: "provider"; descriptor: AnalyticsProviderDescriptor; hasAccessToken: boolean }
@@ -36,7 +36,7 @@ export class WebAnalyticsSettingsDashboardElement extends UmbElementMixin(LitEle
   @state() private _showValidation = false;
   @state() private _testingKey?: string;
   @state() private _status?: { type: "success" | "error"; message: string };
-  @state() private _loadError?: SettingsLoadError;
+  @state() private _loadError?: SettingsError;
   @state() private _connectionStatuses: Record<string, ConnectionActionStatus> = {};
   @state() private _showProviderPicker = false;
 
@@ -50,7 +50,7 @@ export class WebAnalyticsSettingsDashboardElement extends UmbElementMixin(LitEle
     try {
       const { data, error, response } = await WebAnalyticsService.settings();
       if (error || !data) {
-        this._loadError = settingsLoadError(error, response?.status);
+        this._loadError = settingsError("load", error, response?.status);
         return;
       }
       this._settings = data;
@@ -59,7 +59,7 @@ export class WebAnalyticsSettingsDashboardElement extends UmbElementMixin(LitEle
       this._status = undefined;
       this._loadError = undefined;
     } catch (error) {
-      this._loadError = settingsLoadError(error);
+      this._loadError = settingsError("load", error);
     } finally {
       this._loading = false;
     }
@@ -162,13 +162,13 @@ export class WebAnalyticsSettingsDashboardElement extends UmbElementMixin(LitEle
       this._connectionStatuses = {
         ...this._connectionStatuses,
         [key]: error || !data
-          ? { type: "error", message: settingsActionError("test", error, response?.status) }
+          ? { type: "error", message: settingsError("test", error, response?.status).message }
           : { type: data.success ? "success" : "error", message: data.message },
       };
     } catch (error) {
       this._connectionStatuses = {
         ...this._connectionStatuses,
-        [key]: { type: "error", message: settingsActionError("test", error) },
+        [key]: { type: "error", message: settingsError("test", error).message },
       };
     } finally {
       this._testingKey = undefined;
@@ -197,7 +197,7 @@ export class WebAnalyticsSettingsDashboardElement extends UmbElementMixin(LitEle
     try {
       const { data, error, response } = await WebAnalyticsService.saveSettings({ body });
       if (error || !data) {
-        this._status = { type: "error", message: settingsActionError("save", error, response?.status) };
+        this._status = { type: "error", message: settingsError("save", error, response?.status).message };
         return false;
       }
       this._settings = data;
@@ -207,7 +207,7 @@ export class WebAnalyticsSettingsDashboardElement extends UmbElementMixin(LitEle
       if (successMessage) this._status = { type: "success", message: successMessage };
       return true;
     } catch (error) {
-      this._status = { type: "error", message: settingsActionError("save", error) };
+      this._status = { type: "error", message: settingsError("save", error).message };
       return false;
     } finally {
       this._saving = false;
 
@@ -1,31 +1,31 @@
 import { describe, expect, it } from "vitest";
-import { settingsActionError, settingsLoadError } from "./settings-error.js";
+import { settingsError } from "./settings-error.js";
 
-describe("settingsLoadError", () => {
+describe("settingsError", () => {
   it.each([
     [401, "Sign in again", "session has expired"],
     [403, "Administrator access required", "Only administrators"],
     [404, "Package files are out of sync", "server and package files use the same version"],
     [429, "Too many requests", "Wait a moment"],
     [503, "Settings service unavailable", "Umbraco logs"],
   ])("describes HTTP %s with a useful recovery", (status, headline, message) => {
-    expect(settingsLoadError({}, status)).toEqual(expect.objectContaining({ headline }));
-    expect(settingsLoadError({}, status).message).toContain(message);
+    expect(settingsError("load", {}, status)).toEqual(expect.objectContaining({ headline }));
+    expect(settingsError("load", {}, status).message).toContain(message);
   });
 
   it("uses a network recovery message when no response exists", () => {
-    expect(settingsLoadError(new TypeError("Failed to fetch"))).toEqual({
+    expect(settingsError("load", new TypeError("Failed to fetch"))).toEqual({
       headline: "Could not reach the settings service",
       message: "Check your connection and that Umbraco is running, then retry loading Web Analytics settings.",
     });
   });
 
   it("uses a status carried by an SDK error when no response is available", () => {
-    expect(settingsLoadError({ status: 403 }).headline).toBe("Administrator access required");
+    expect(settingsError("load", { status: 403 }).headline).toBe("Administrator access required");
   });
 });
 
-describe("settingsActionError", () => {
+describe("settings actions", () => {
   it.each([
     ["save", 401, "session has expired"],
     ["save", 404, "server and package files use the same version"],
@@ -34,16 +34,16 @@ describe("settingsActionError", () => {
     ["test", 404, "connection test API was not found"],
     ["test", 503, "Umbraco logs"],
   ] as const)("describes %s HTTP %s failures", (action, status, message) => {
-    expect(settingsActionError(action, {}, status)).toContain(message);
+    expect(settingsError(action, {}, status).message).toContain(message);
   });
 
   it("preserves a server validation detail when saving", () => {
-    expect(settingsActionError("save", { detail: "Cache duration must use hh:mm:ss." }, 400))
+    expect(settingsError("save", { detail: "Cache duration must use hh:mm:ss." }, 400).message)
       .toBe("Cache duration must use hh:mm:ss.");
   });
 
   it("describes rejected requests as connection failures", () => {
-    expect(settingsActionError("save", new TypeError("Failed to fetch"))).toContain("could not reach Umbraco");
-    expect(settingsActionError("test", new TypeError("Failed to fetch"))).toContain("could not reach Umbraco");
+    expect(settingsError("save", new TypeError("Failed to fetch")).message).toContain("could not reach Umbraco");
+    expect(settingsError("test", new TypeError("Failed to fetch")).message).toContain("could not reach Umbraco");
   });
 });
@@ -1,81 +1,44 @@
-export interface SettingsLoadError {
+import { apiFailure } from "../api/api-failure.js";
+
+export interface SettingsError {
   headline: string;
   message: string;
 }
 
-export type SettingsAction = "save" | "test";
+export type SettingsOperation = "load" | "save" | "test";
 
-export function settingsLoadError(error: unknown, responseStatus?: number): SettingsLoadError {
-  const status = requestStatus(error, responseStatus);
+export function settingsError(operation: SettingsOperation, error: unknown, responseStatus?: number): SettingsError {
+  const failure = apiFailure(error, responseStatus);
+  const retryAction = operation === "load" ? "retry loading Web Analytics settings" : operation === "save" ? "save your preserved changes" : "retry the connection test";
+  const subject = operation === "test" ? "The connection test" : "Web Analytics settings";
 
-  switch (status) {
-    case 401:
-      return {
-        headline: "Sign in again",
-        message: "Your backoffice session has expired. Sign in again, then retry loading Web Analytics settings.",
-      };
-    case 403:
-      return {
-        headline: "Administrator access required",
-        message: "Only administrators can manage Web Analytics settings. Ask an administrator to open this page.",
-      };
-    case 404:
-      return {
-        headline: "Package files are out of sync",
-        message: "The settings API was not found. Restart Umbraco after updating Web Analytics, then refresh the backoffice so the server and package files use the same version.",
-      };
-    case 429:
-      return {
-        headline: "Too many requests",
-        message: "Web Analytics settings cannot be loaded right now. Wait a moment, then retry.",
-      };
-    default:
-      if (status !== undefined && status >= 500) {
-        return {
-          headline: "Settings service unavailable",
-          message: "Umbraco could not load Web Analytics settings. Retry, and check the Umbraco logs if the problem continues.",
-        };
-      }
-      return {
-        headline: "Could not reach the settings service",
-        message: "Check your connection and that Umbraco is running, then retry loading Web Analytics settings.",
-      };
-  }
-}
-
-export function settingsActionError(action: SettingsAction, error: unknown, responseStatus?: number): string {
-  const status = requestStatus(error, responseStatus);
-  const subject = action === "save" ? "Web Analytics settings" : "The connection test";
-
-  switch (status) {
+  switch (failure.status) {
     case 400:
-      return action === "save"
-        ? problemDetail(error) ?? "Settings were not saved. Review the connection fields and mapping values."
-        : "The connection test request was invalid. Check the saved connection configuration.";
+      return operation === "save"
+        ? { headline: "Review the settings", message: failure.detail ?? "Settings were not saved. Review the connection fields and mapping values." }
+        : operation === "test"
+          ? { headline: "Invalid connection test", message: "The connection test request was invalid. Check the saved connection configuration." }
+          : unavailable("Settings request rejected", "Umbraco rejected the settings request. Refresh the backoffice, then retry.");
     case 401:
-      return `Your backoffice session has expired. Sign in again, then ${action === "save" ? "save your preserved changes" : "retry the connection test"}.`;
+      return unavailable("Sign in again", `Your backoffice session has expired. Sign in again, then ${retryAction}.`);
     case 403:
-      return `Administrator access is required to ${action === "save" ? "save Web Analytics settings" : "test analytics connections"}.`;
+      return unavailable("Administrator access required", operation === "load"
+        ? "Only administrators can manage Web Analytics settings. Ask an administrator to open this page."
+        : `Administrator access is required to ${operation === "save" ? "save Web Analytics settings" : "test analytics connections"}.`);
     case 404:
-      return `${subject} API was not found. Restart Umbraco after updating Web Analytics, then refresh the backoffice so the server and package files use the same version.`;
+      return unavailable("Package files are out of sync", `${operation === "load" ? "The settings" : subject} API was not found. Restart Umbraco after updating Web Analytics, then refresh the backoffice so the server and package files use the same version.`);
     case 429:
-      return `${subject} could not be completed because there were too many requests. Wait a moment, then retry.`;
+      return unavailable("Too many requests", `${subject} ${operation === "load" ? "cannot be loaded" : "could not be completed"} right now. Wait a moment, then retry.`);
     default:
-      if (status !== undefined && status >= 500) {
-        return `${subject} could not be completed. Retry, and check the Umbraco logs if the problem continues.`;
+      if (failure.status !== undefined && failure.status >= 500) {
+        return unavailable("Settings service unavailable", `${subject} could not be ${operation === "load" ? "loaded" : "completed"}. Retry, and check the Umbraco logs if the problem continues.`);
       }
-      return `${subject} could not reach Umbraco. Check your connection and that Umbraco is running, then retry.`;
+      return operation === "load"
+        ? unavailable("Could not reach the settings service", "Check your connection and that Umbraco is running, then retry loading Web Analytics settings.")
+        : unavailable("Could not reach the settings service", `${subject} could not reach Umbraco. Check your connection and that Umbraco is running, then retry.`);
   }
 }
 
-function requestStatus(error: unknown, responseStatus?: number): number | undefined {
-  const errorStatus = typeof error === "object" && error !== null && "status" in error
-    ? Number(error.status)
-    : undefined;
-  return responseStatus || errorStatus;
-}
-
-function problemDetail(error: unknown): string | undefined {
-  if (typeof error !== "object" || error === null || !("detail" in error)) return undefined;
-  return typeof error.detail === "string" && error.detail.trim() ? error.detail : undefined;
+function unavailable(headline: string, message: string): SettingsError {
+  return { headline, message };
 }