From e7d6e7946c4d4b4f44f5f8ae6d2d4f466a92370e Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Wed, 30 Sep 2026 18:37:03 -0700
Subject: [PATCH 01/12] fix(commerce-server): return 400/404 from order-status
 instead of 500

Invalid order IDs (blank, padded, `.`, `..`) and missing orders previously
surfaced as 500s, indistinguishable from credential or upstream failures.

- getOrderStatus throws InvalidOrderIdError for invalid IDs and
  OrderNotFoundError when the Orders API returns 404 or the order is bound
  to another order ID, store, or channel. Incomplete responses stay generic.
- The order-status route maps these to 400 and 404; everything else is 500.
- Padded IDs are rejected rather than trimmed so the lookup never targets a
  different ID than the caller supplied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/clear-order-status-errors.md       |   5 +
 packages/commerce-server/README.md            |   2 +-
 .../src/get-order-status.test.ts              | 116 ++++++++++++++++--
 packages/commerce-server/src/index.ts         |   2 +
 .../src/lib/commerce/get-order-status.ts      |  33 ++++-
 .../server/api/commerce/order-status/GET.ts   |  22 +++-
 6 files changed, 161 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/clear-order-status-errors.md

diff --git a/.changeset/clear-order-status-errors.md b/.changeset/clear-order-status-errors.md
new file mode 100644
index 00000000..dda3fadf
--- /dev/null
+++ b/.changeset/clear-order-status-errors.md
@@ -0,0 +1,5 @@
+---
+'@godaddy/gd-commerce-server': patch
+---
+
+Return 400 from the order-status route for invalid order IDs and 404 when the order is missing or belongs to another store or channel, instead of 500. Export `InvalidOrderIdError` and `OrderNotFoundError` for in-process `getOrderStatus()` callers.
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index eb867c1f..71c69439 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -56,4 +56,4 @@ Configure `checkoutReturnUrls` on the router using trusted deployment settings.
 
 Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of `createCheckoutSession()` own their return URLs and must construct or validate them server-side.
 
-A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; `unknown` if absent). The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; `unknown` if absent). The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID and 404 when the Orders API has no such order or the order belongs to another store or channel; credential and other upstream failures return 500. In-process callers can check for the exported `InvalidOrderIdError` and `OrderNotFoundError`. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index ca89fc3f..ae6a033b 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -2,7 +2,7 @@ import { once } from 'node:events';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { createRuntimeCommerceConfiguration } from './lib/commerce/config';
-import { getOrderStatus } from './lib/commerce/get-order-status';
+import { getOrderStatus, InvalidOrderIdError, OrderNotFoundError } from './lib/commerce/get-order-status';
 import { createGoDaddyPaymentsRouter } from './router';
 
 const clientFetch = globalThis.fetch;
@@ -126,20 +126,42 @@ describe('authorized order lookup', () => {
     },
   );
 
+  it.each([undefined, { ...order, context: undefined }])(
+    'rejects an incomplete order response',
+    async (result): Promise<void> => {
+      upstream
+        .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+        .mockResolvedValueOnce(Response.json({ order: result }));
+      const lookup = getOrderStatus(order.id, configuration);
+      await expect(lookup).rejects.toThrow('Order lookup did not return the requested order');
+      await expect(lookup).rejects.not.toBeInstanceOf(OrderNotFoundError);
+    },
+  );
+
   it.each([
-    undefined,
     { ...order, id: 'another-order' },
     { ...order, context: { ...order.context, storeId: 'another-store' } },
     { ...order, context: { ...order.context, channelId: 'another-channel' } },
-    { ...order, context: undefined },
-  ])('rejects missing or mismatched order bindings', async (result): Promise<void> => {
+  ])(
+    'reports an order bound to another order, store, or channel as not found',
+    async (result): Promise<void> => {
+      upstream
+        .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+        .mockResolvedValueOnce(Response.json({ order: result }));
+      await expect(getOrderStatus(order.id, configuration)).rejects.toBeInstanceOf(OrderNotFoundError);
+    },
+  );
+
+  it('reports an upstream 404 as not found without exposing its body', async (): Promise<void> => {
     upstream
       .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
-      .mockResolvedValueOnce(Response.json({ order: result }));
-    await expect(getOrderStatus(order.id, configuration)).rejects.toThrow('Order lookup');
+      .mockResolvedValueOnce(new Response('Private upstream details', { status: 404 }));
+    const lookup = getOrderStatus(order.id, configuration);
+    await expect(lookup).rejects.toBeInstanceOf(OrderNotFoundError);
+    await expect(lookup).rejects.toThrow(/^Order not found$/);
   });
 
-  it.each([401, 403, 404, 500])(
+  it.each([401, 403, 500])(
     'preserves an upstream order lookup failure (%i) without exposing its body',
     async (status): Promise<void> => {
       upstream
@@ -157,11 +179,87 @@ describe('authorized order lookup', () => {
     expect(upstream).toHaveBeenCalledTimes(1);
   });
 
-  it.each(['', ' ', '.', '..'])(
+  it.each(['', ' ', '.', '..', ' completed-order', 'completed-order\n'])(
     'rejects invalid order ID %j before requesting credentials',
     async (id): Promise<void> => {
-      await expect(getOrderStatus(id, configuration)).rejects.toThrow('a valid orderId is required');
+      const lookup = getOrderStatus(id, configuration);
+      await expect(lookup).rejects.toBeInstanceOf(InvalidOrderIdError);
+      await expect(lookup).rejects.toThrow('a valid orderId is required');
       expect(upstream).not.toHaveBeenCalled();
     },
   );
 });
+
+describe('order-status route', () => {
+  async function requestOrderStatus(query: string): Promise<{ status: number; body: unknown }> {
+    const app = express();
+    app.use('/api/commerce', createGoDaddyPaymentsRouter(configuration));
+    const server = app.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    try {
+      const address = server.address();
+      if (!address || typeof address === 'string') throw new Error('Expected a listening TCP server');
+      const response = await clientFetch(
+        `http://127.0.0.1:${address.port}/api/commerce/order-status${query}`,
+      );
+      return { status: response.status, body: await response.json() };
+    } finally {
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+    }
+  }
+
+  it.each([
+    '',
+    '?orderId=',
+    '?orderId=%20',
+    '?orderId=.',
+    '?orderId=..',
+    '?orderId=%20cart-1',
+    '?orderId=a&orderId=b',
+  ])(
+    'returns 400 for invalid order ID query %j without an upstream request',
+    async (query): Promise<void> => {
+      await expect(requestOrderStatus(query)).resolves.toEqual({
+        status: 400,
+        body: { success: false, error: 'missing or invalid orderId query parameter' },
+      });
+      expect(upstream).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([
+    ['an upstream 404', new Response('Private upstream details', { status: 404 })],
+    [
+      'another store',
+      Response.json({ order: { ...order, context: { ...order.context, storeId: 'another-store' } } }),
+    ],
+  ])('returns 404 for %s', async (_case, orderResponse): Promise<void> => {
+    upstream
+      .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+      .mockResolvedValueOnce(orderResponse);
+    await expect(requestOrderStatus(`?orderId=${order.id}`)).resolves.toEqual({
+      status: 404,
+      body: { success: false, error: 'Order not found' },
+    });
+  });
+
+  it.each([
+    ['a denied token', [new Response('Invalid scope', { status: 403 })]],
+    [
+      'an upstream 500',
+      [
+        Response.json({ access_token: 'order-token' }),
+        new Response('Private upstream details', { status: 500 }),
+      ],
+    ],
+    ['an incomplete order', [Response.json({ access_token: 'order-token' }), Response.json({})]],
+  ])('returns 500 for %s', async (_case, responses): Promise<void> => {
+    for (const response of responses) upstream.mockResolvedValueOnce(response);
+    const result = await requestOrderStatus(`?orderId=${order.id}`);
+    expect(result.status).toBe(500);
+    expect(result.body).toMatchObject({ success: false, error: 'Failed to get order status' });
+    expect(JSON.stringify(result.body)).not.toContain('Private upstream details');
+  });
+});
diff --git a/packages/commerce-server/src/index.ts b/packages/commerce-server/src/index.ts
index fd69b46b..596de819 100644
--- a/packages/commerce-server/src/index.ts
+++ b/packages/commerce-server/src/index.ts
@@ -19,6 +19,8 @@ export {
 export {
   type CommerceOrderStatus,
   getOrderStatus,
+  InvalidOrderIdError,
+  OrderNotFoundError,
 } from './lib/commerce/get-order-status';
 export {
   type CommerceRouterFeatures,
diff --git a/packages/commerce-server/src/lib/commerce/get-order-status.ts b/packages/commerce-server/src/lib/commerce/get-order-status.ts
index a01c66a3..83e290f6 100644
--- a/packages/commerce-server/src/lib/commerce/get-order-status.ts
+++ b/packages/commerce-server/src/lib/commerce/get-order-status.ts
@@ -23,6 +23,20 @@ export interface CommerceOrderStatus {
   lineItems?: unknown[];
 }
 
+export class InvalidOrderIdError extends Error {
+  constructor() {
+    super('getOrderStatus: a valid orderId is required');
+    this.name = 'InvalidOrderIdError';
+  }
+}
+
+export class OrderNotFoundError extends Error {
+  constructor() {
+    super('Order not found');
+    this.name = 'OrderNotFoundError';
+  }
+}
+
 interface OrderResponse {
   order?: {
     id: string;
@@ -39,8 +53,15 @@ export async function getOrderStatus(
   orderId: string,
   configuration: CommerceConfiguration = createRuntimeCommerceConfiguration(),
 ): Promise<CommerceOrderStatus> {
-  if (typeof orderId !== 'string' || !orderId.trim() || orderId === '.' || orderId === '..') {
-    throw new Error('getOrderStatus: a valid orderId is required');
+  // `.` and `..` survive encodeURIComponent and would resolve the URL to the store resource.
+  if (
+    typeof orderId !== 'string' ||
+    !orderId ||
+    orderId !== orderId.trim() ||
+    orderId === '.' ||
+    orderId === '..'
+  ) {
+    throw new InvalidOrderIdError();
   }
 
   const { storeId, channelId, clientId, clientSecret, apiBaseUrl, currencyCode } = configuration.read();
@@ -61,13 +82,15 @@ export async function getOrderStatus(
       cache: 'no-store',
     },
   );
+  if (response.status === 404) throw new OrderNotFoundError();
   if (!response.ok) throw new Error(`Failed to load order: upstream returned ${response.status}`);
 
   const data = (await response.json()) as OrderResponse;
   const order = data?.order;
-  if (!order?.id || order.id !== orderId) throw new Error('Order lookup did not return the requested order');
-  if (order.context?.storeId !== storeId || order.context?.channelId !== channelId) {
-    throw new Error('Order lookup returned a different store or channel');
+  if (!order?.id || !order.context) throw new Error('Order lookup did not return the requested order');
+  // Report an order bound to another store or channel as missing so the route doesn't reveal it exists.
+  if (order.id !== orderId || order.context.storeId !== storeId || order.context.channelId !== channelId) {
+    throw new OrderNotFoundError();
   }
   const total = order.totals?.total;
 
diff --git a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
index 797f5404..82f892a1 100644
--- a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
@@ -11,26 +11,40 @@
  * Query:
  *   orderId  - GoDaddy order id (required)
  *
- * Response: { success: true, order: CommerceOrderStatus }
- *   order.status is the payment status returned by the authorized Orders API.
+ * Responses:
+ *   200 { success: true, order: CommerceOrderStatus }
+ *       order.status is the payment status returned by the authorized Orders API.
+ *   400 missing, blank, padded, `.` or `..` orderId
+ *   404 no order with that id in the configured store and channel
+ *   500 credential, upstream, or configuration failure
  * The host must authorize the caller's access to the requested order.
  */
 import type { Request, Response } from 'express';
 
 import { commerceConfigurationForResponse } from '@/lib/commerce/config';
-import { getOrderStatus } from '@/lib/commerce/get-order-status';
+import { getOrderStatus, InvalidOrderIdError, OrderNotFoundError } from '@/lib/commerce/get-order-status';
+
+const invalidOrderIdBody = { success: false, error: 'missing or invalid orderId query parameter' };
 
 export default async function handler(req: Request, res: Response): Promise<void> {
   try {
     const { orderId } = req.query;
     if (!orderId || typeof orderId !== 'string') {
-      res.status(400).json({ success: false, error: 'missing or invalid orderId query parameter' });
+      res.status(400).json(invalidOrderIdBody);
       return;
     }
 
     const order = await getOrderStatus(orderId, commerceConfigurationForResponse(res));
     res.status(200).json({ success: true, order });
   } catch (error) {
+    if (error instanceof InvalidOrderIdError) {
+      res.status(400).json(invalidOrderIdBody);
+      return;
+    }
+    if (error instanceof OrderNotFoundError) {
+      res.status(404).json({ success: false, error: 'Order not found' });
+      return;
+    }
     res.status(500).json({
       success: false,
       error: 'Failed to get order status',

From 0482854e9d24dc397c2867d94390dd7ac0f382d6 Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 12:20:50 -0700
Subject: [PATCH 02/12] fix(commerce-server): keep order-status 500 detail
 server-side

The 500 body echoed the internal error message, which can name upstream
HTTP statuses, OAuth/token failures, or configuration problems. Return only
{ success: false, error } and log the detail with console.error.

Export ORDER_STATUS_UNKNOWN so callers compare against a constant rather than
the 'unknown' literal; status stays a string because the Orders API's full
paymentStatus set is not documented here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/clear-order-status-errors.md        |  2 +-
 packages/commerce-server/README.md             |  2 +-
 .../src/get-order-status.test.ts               | 18 +++++++++++-------
 packages/commerce-server/src/index.ts          |  1 +
 .../src/lib/commerce/get-order-status.ts       |  7 +++++--
 .../server/api/commerce/order-status/GET.ts    |  8 +++-----
 6 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/.changeset/clear-order-status-errors.md b/.changeset/clear-order-status-errors.md
index dda3fadf..6ae979f0 100644
--- a/.changeset/clear-order-status-errors.md
+++ b/.changeset/clear-order-status-errors.md
@@ -2,4 +2,4 @@
 '@godaddy/gd-commerce-server': patch
 ---
 
-Return 400 from the order-status route for invalid order IDs and 404 when the order is missing or belongs to another store or channel, instead of 500. Export `InvalidOrderIdError` and `OrderNotFoundError` for in-process `getOrderStatus()` callers.
+Return 400 from the order-status route for invalid order IDs and 404 when the order is missing or belongs to another store or channel, instead of 500. The 500 response no longer includes the internal error message; it is logged server-side instead. Export `InvalidOrderIdError`, `OrderNotFoundError`, and `ORDER_STATUS_UNKNOWN` for in-process `getOrderStatus()` callers.
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index 71c69439..4a961c22 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -56,4 +56,4 @@ Configure `checkoutReturnUrls` on the router using trusted deployment settings.
 
 Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of `createCheckoutSession()` own their return URLs and must construct or validate them server-side.
 
-A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; `unknown` if absent). The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID and 404 when the Orders API has no such order or the order belongs to another store or channel; credential and other upstream failures return 500. In-process callers can check for the exported `InvalidOrderIdError` and `OrderNotFoundError`. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) and 404 when the Orders API has no such order or the order belongs to another store or channel. Credential and other upstream failures return 500 with a generic body; the detail is logged server-side with `console.error`. In-process callers can check for the exported `InvalidOrderIdError` and `OrderNotFoundError`. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index ae6a033b..3b94ffd2 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -255,11 +255,15 @@ describe('order-status route', () => {
       ],
     ],
     ['an incomplete order', [Response.json({ access_token: 'order-token' }), Response.json({})]],
-  ])('returns 500 for %s', async (_case, responses): Promise<void> => {
-    for (const response of responses) upstream.mockResolvedValueOnce(response);
-    const result = await requestOrderStatus(`?orderId=${order.id}`);
-    expect(result.status).toBe(500);
-    expect(result.body).toMatchObject({ success: false, error: 'Failed to get order status' });
-    expect(JSON.stringify(result.body)).not.toContain('Private upstream details');
-  });
+  ])(
+    'returns a generic 500 for %s and logs the detail server-side',
+    async (_case, responses): Promise<void> => {
+      const log = vi.spyOn(console, 'error').mockImplementation((): void => {});
+      for (const response of responses) upstream.mockResolvedValueOnce(response);
+      const result = await requestOrderStatus(`?orderId=${order.id}`);
+      expect(result).toEqual({ status: 500, body: { success: false, error: 'Failed to get order status' } });
+      expect(log).toHaveBeenCalledWith('order-status: failed to get order status', expect.any(Error));
+      log.mockRestore();
+    },
+  );
 });
diff --git a/packages/commerce-server/src/index.ts b/packages/commerce-server/src/index.ts
index 596de819..385a8993 100644
--- a/packages/commerce-server/src/index.ts
+++ b/packages/commerce-server/src/index.ts
@@ -20,6 +20,7 @@ export {
   type CommerceOrderStatus,
   getOrderStatus,
   InvalidOrderIdError,
+  ORDER_STATUS_UNKNOWN,
   OrderNotFoundError,
 } from './lib/commerce/get-order-status';
 export {
diff --git a/packages/commerce-server/src/lib/commerce/get-order-status.ts b/packages/commerce-server/src/lib/commerce/get-order-status.ts
index 83e290f6..d460e462 100644
--- a/packages/commerce-server/src/lib/commerce/get-order-status.ts
+++ b/packages/commerce-server/src/lib/commerce/get-order-status.ts
@@ -6,10 +6,13 @@ import { authorizationHeaders, getOAuthAccessToken } from './checkout-subgraph';
 import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './config';
 import type { Money } from './gql';
 
+/** `CommerceOrderStatus.status` when the Orders API reports no payment status. */
+export const ORDER_STATUS_UNKNOWN = 'unknown';
+
 export interface CommerceOrderStatus {
   /** GoDaddy order id. */
   id: string;
-  /** Payment status reported by Commerce, or 'unknown' when it is unavailable. */
+  /** Payment status reported by Commerce (e.g. `PAID`, `PENDING`), or `ORDER_STATUS_UNKNOWN`. */
   status: string;
   /** Total amount in the currency's smallest unit (cents for USD). */
   amount: number;
@@ -96,7 +99,7 @@ export async function getOrderStatus(
 
   return {
     id: order.id,
-    status: order.statuses?.paymentStatus ?? 'unknown',
+    status: order.statuses?.paymentStatus ?? ORDER_STATUS_UNKNOWN,
     amount: total?.value ?? 0,
     currency: total?.currencyCode ?? currencyCode,
     createdAt: order.createdAt,
diff --git a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
index 82f892a1..6de46885 100644
--- a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
@@ -45,10 +45,8 @@ export default async function handler(req: Request, res: Response): Promise<void
       res.status(404).json({ success: false, error: 'Order not found' });
       return;
     }
-    res.status(500).json({
-      success: false,
-      error: 'Failed to get order status',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    // The detail can name upstream statuses, credentials, or configuration, so it stays server-side.
+    console.error('order-status: failed to get order status', error);
+    res.status(500).json({ success: false, error: 'Failed to get order status' });
   }
 }

From 85dedbe50f38cd32985f4e9dd5209b3204a0a7f7 Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 12:50:46 -0700
Subject: [PATCH 03/12] fix(commerce-server): stop leaking internal error text
 from 500 responses

Ten catalog, cart, and checkout routes returned the raw upstream error
message in their 500 bodies. They now respond with only the generic error
label and log the detail server-side via a shared respondWithFailure helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/quiet-route-failures.md            |  5 ++
 .../src/configuration-integration.test.ts     | 16 +++--
 .../src/lib/commerce/route-failure.ts         |  6 ++
 packages/commerce-server/src/router.test.ts   | 61 ++++++++++++++++++-
 .../src/server/api/commerce/cart/POST.ts      |  6 +-
 .../src/server/api/commerce/cart/[id]/GET.ts  |  6 +-
 .../api/commerce/cart/[id]/discounts/POST.ts  |  6 +-
 .../api/commerce/cart/[id]/items/POST.ts      |  6 +-
 .../cart/[id]/items/[itemId]/DELETE.ts        |  6 +-
 .../cart/[id]/items/[itemId]/PATCH.ts         |  6 +-
 .../src/server/api/commerce/checkout/POST.ts  |  6 +-
 .../src/server/api/commerce/products/GET.ts   |  6 +-
 .../server/api/commerce/products/[id]/GET.ts  |  6 +-
 .../src/server/api/commerce/skus/[id]/GET.ts  |  6 +-
 14 files changed, 100 insertions(+), 48 deletions(-)
 create mode 100644 .changeset/quiet-route-failures.md
 create mode 100644 packages/commerce-server/src/lib/commerce/route-failure.ts

diff --git a/.changeset/quiet-route-failures.md b/.changeset/quiet-route-failures.md
new file mode 100644
index 00000000..eb7aad3e
--- /dev/null
+++ b/.changeset/quiet-route-failures.md
@@ -0,0 +1,5 @@
+---
+'@godaddy/gd-commerce-server': patch
+---
+
+Stop returning the internal error message in 500 responses from the catalog, cart, and checkout routes. These routes now respond with only `{ "error": "<label>" }` and log the underlying error server-side with `console.error`. Hosts that read `message` from these responses should log server-side instead.
diff --git a/packages/commerce-server/src/configuration-integration.test.ts b/packages/commerce-server/src/configuration-integration.test.ts
index c6a0a421..18459a18 100644
--- a/packages/commerce-server/src/configuration-integration.test.ts
+++ b/packages/commerce-server/src/configuration-integration.test.ts
@@ -7,6 +7,7 @@ import { createCommerceRouter } from './router';
 const clientFetch = globalThis.fetch;
 afterEach((): void => {
   vi.unstubAllGlobals();
+  vi.restoreAllMocks();
 });
 
 it('serves variant product details without querying SKUGroup.status', async (): Promise<void> => {
@@ -237,15 +238,12 @@ it.each([undefined, 'https://api.example.com', 'https://api.example.com:8443'])(
 
 it.each([
   ['Order not found', 200, { cart: null }],
-  [
-    'Authentication token expired',
-    500,
-    { error: 'Failed to load cart', message: 'Authentication token expired' },
-  ],
-  ['Database unavailable', 500, { error: 'Failed to load cart', message: 'Database unavailable' }],
+  ['Authentication token expired', 500, { error: 'Failed to load cart' }],
+  ['Database unavailable', 500, { error: 'Failed to load cart' }],
 ] as const)(
   'handles the actual Apollo error envelope for %s',
   async (message, status, body): Promise<void> => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
     vi.stubGlobal(
       'fetch',
       vi.fn(
@@ -279,6 +277,12 @@ it.each([
       const response = await clientFetch(`http://127.0.0.1:${address.port}/api/commerce/cart/completed-cart`);
       expect(response.status).toBe(status);
       expect(await response.json()).toEqual(body);
+      if (status === 500) {
+        expect(consoleError).toHaveBeenCalledWith(
+          'commerce-server: Failed to load cart',
+          expect.objectContaining({ message: expect.stringContaining(message) }),
+        );
+      }
     } finally {
       await new Promise<void>((resolve, reject) =>
         server.close((error) => (error ? reject(error) : resolve())),
diff --git a/packages/commerce-server/src/lib/commerce/route-failure.ts b/packages/commerce-server/src/lib/commerce/route-failure.ts
new file mode 100644
index 00000000..a149c878
--- /dev/null
+++ b/packages/commerce-server/src/lib/commerce/route-failure.ts
@@ -0,0 +1,6 @@
+import type { Response } from 'express';
+
+export function respondWithFailure(res: Response, label: string, error: unknown): void {
+  console.error(`commerce-server: ${label}`, error);
+  res.status(500).json({ error: label });
+}
diff --git a/packages/commerce-server/src/router.test.ts b/packages/commerce-server/src/router.test.ts
index bcd07e95..d49fe07b 100644
--- a/packages/commerce-server/src/router.test.ts
+++ b/packages/commerce-server/src/router.test.ts
@@ -1,7 +1,7 @@
 import type { AddressInfo } from 'node:net';
 import type { Request, Response } from 'express';
 import express from 'express';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { getCommerceCartScope } from './lib/commerce/cart-scope';
 import type { CommerceConfiguration } from './lib/commerce/config';
 import { createCheckoutSession } from './lib/commerce/create-checkout-session';
@@ -62,6 +62,10 @@ describe('Commerce scoped routes', () => {
     vi.clearAllMocks();
   });
 
+  afterEach((): void => {
+    vi.restoreAllMocks();
+  });
+
   it('does not query unsupported status fields on the storefront cart API', (): void => {
     expect(getCartOrderQuery).not.toMatch(/\bstatuses\s*\{/);
   });
@@ -285,6 +289,7 @@ describe('Commerce scoped routes', () => {
       { code: 'FORBIDDEN', message: 'Access denied', status: 403 },
     ]),
   ])('preserves the cart on unrelated upstream failures: %s', async (error): Promise<void> => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
     const res = response();
     vi.mocked(gqlRequest).mockRejectedValueOnce(error);
     await readCart(
@@ -292,7 +297,8 @@ describe('Commerce scoped routes', () => {
       res as unknown as Response,
     );
     expect(res.status).toHaveBeenCalledWith(500);
-    expect(res.json).toHaveBeenCalledWith({ error: 'Failed to load cart', message: error.message });
+    expect(res.json).toHaveBeenCalledWith({ error: 'Failed to load cart' });
+    expect(consoleError).toHaveBeenCalledWith('commerce-server: Failed to load cart', error);
   });
 
   it.each([
@@ -337,6 +343,57 @@ describe('Commerce scoped routes', () => {
       });
     },
   );
+
+  const scopedRequest = {
+    headers: {},
+    query: {},
+    params: { id: 'id-1', itemId: 'item-1' },
+    body: {
+      skuId: 'sku-1',
+      name: 'Product',
+      quantity: 1,
+      discountCodes: ['PROMO'],
+      lineItems: [{ skuId: 'sku-1', name: 'Product', quantity: 1 }],
+    },
+  } as unknown as Request;
+
+  it.each([
+    ['products', readProducts, 'Failed to load products'],
+    ['product', readProduct, 'Failed to load product'],
+    ['sku', readSku, 'Failed to load sku'],
+    ['create cart', createCart, 'Failed to create cart'],
+    ['read cart', readCart, 'Failed to load cart'],
+    ['add item', addItem, 'Failed to add line item'],
+    ['update item', updateItem, 'Failed to update line item'],
+    ['delete item', deleteItem, 'Failed to delete line item'],
+    ['discounts', applyDiscount, 'Failed to apply discount codes'],
+    ['checkout', checkout, 'Failed to create checkout session'],
+  ] as const)(
+    'returns a generic 500 and logs the detail for %s',
+    async (_name, handler, label): Promise<void> => {
+      const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const failure = new Error('GraphQL request failed: 502 secret-upstream-detail');
+      vi.mocked(gqlRequest).mockRejectedValue(failure);
+      vi.mocked(createCheckoutSession).mockRejectedValue(failure);
+      const res = response();
+      (res.locals as Record<string, unknown>).commerceCheckoutReturnUrlValidator = (
+        returnUrl?: string,
+        successUrl?: string,
+      ) => ({ returnUrl, successUrl });
+      const req = {
+        ...scopedRequest,
+        body: {
+          ...(scopedRequest.body as object),
+          ...(handler === checkout ? { lineItems: undefined, skuId: 'sku-1' } : {}),
+        },
+      } as unknown as Request;
+      await handler(req, res as unknown as Response);
+      expect(res.status).toHaveBeenCalledWith(500);
+      expect(res.json).toHaveBeenCalledTimes(1);
+      expect(res.json).toHaveBeenCalledWith({ error: label });
+      expect(consoleError).toHaveBeenCalledWith(`commerce-server: ${label}`, failure);
+    },
+  );
 });
 
 describe('Commerce router mounting', (): void => {
diff --git a/packages/commerce-server/src/server/api/commerce/cart/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/POST.ts
index c249a905..bbe7be74 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/POST.ts
@@ -41,6 +41,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const addCartOrderMutation = `
   mutation AddCartOrder($input: AddDraftOrderInput!) {
@@ -135,9 +136,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.status(201).json({ cart: hydrated.orderById ?? null });
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to create cart',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to create cart', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
index 436a2900..ef27b35a 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
@@ -25,6 +25,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 function isCartNotFoundError(error: unknown): boolean {
   if (!(error instanceof GraphQLErrorWithCodes)) {
@@ -79,9 +80,6 @@ export default async function handler(req: Request, res: Response): Promise<void
       return;
     }
 
-    res.status(500).json({
-      error: 'Failed to load cart',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to load cart', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
index d995e73b..823012c6 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
@@ -25,6 +25,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const applyDiscountCodesMutation = `
   mutation ApplyDiscountCodes($input: ApplyDiscountCodesInput!) {
@@ -78,9 +79,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.json({ cart: hydrated.orderById ?? null });
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to apply discount codes',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to apply discount codes', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
index cc09744d..0c52a11a 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
@@ -28,6 +28,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const addLineItemBySkuIdMutation = `
   mutation AddLineItemBySkuId($input: AddLineItemInput!) {
@@ -82,9 +83,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.status(201).json({ cart: hydrated.orderById ?? null });
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to add line item',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to add line item', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
index 8ea0adb6..c35457c1 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
@@ -22,6 +22,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const deleteLineItemByIdMutation = `
   mutation DeleteLineItemById($id: ID!, $orderId: ID!) {
@@ -60,9 +61,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.json({ cart: hydrated.orderById ?? null });
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to delete line item',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to delete line item', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
index e77360b6..a68e3092 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
@@ -26,6 +26,7 @@ import {
   type UpdateLineItemByIdResult,
   type UpdateLineItemByIdVariables,
 } from '@/lib/commerce/order-subgraph';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const updateLineItemByIdMutation = `
   mutation UpdateLineItemById($input: UpdateLineItemByIdInput!) {
@@ -80,9 +81,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.json({ cart: hydrated.orderById ?? null });
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to update line item',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to update line item', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/checkout/POST.ts b/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
index 42dd56c0..bd6d7b31 100644
--- a/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
@@ -45,6 +45,7 @@ import {
   type CreateCheckoutSessionParams,
   createCheckoutSession,
 } from '@/lib/commerce/create-checkout-session';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 type CheckoutBody = Partial<CreateCheckoutSessionParams>;
 
@@ -104,9 +105,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.status(200).json(session);
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to create checkout session',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to create checkout session', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/products/GET.ts b/packages/commerce-server/src/server/api/commerce/products/GET.ts
index e2ccfb7b..550c4bab 100644
--- a/packages/commerce-server/src/server/api/commerce/products/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/products/GET.ts
@@ -27,6 +27,7 @@ import {
 } from '@/lib/commerce/catalog-subgraph';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 // Cards use group pricing/media and SKU identity/inventory for quick-add.
 // Nested SKU price money fields would exceed the catalog API's depth limit of 10.
@@ -153,9 +154,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.json(data);
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to load products',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to load products', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts b/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts
index 3b9f8ce4..4954aa18 100644
--- a/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts
@@ -26,6 +26,7 @@ import {
 } from '@/lib/commerce/catalog-subgraph';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 type ProductDetailsResult = SkuGroupResult & { activeSkuGroups?: SkuGroupsResult['skuGroups'] };
 
@@ -157,9 +158,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.json({ skuGroup: data.skuGroup });
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to load product',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to load product', error);
   }
 }
diff --git a/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts b/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts
index f5373276..f736e3dd 100644
--- a/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts
@@ -16,6 +16,7 @@ import {
 } from '@/lib/commerce/catalog-subgraph';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
+import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const skuQuery = `
   query Sku($id: String!) {
@@ -95,9 +96,6 @@ export default async function handler(req: Request, res: Response): Promise<void
 
     res.json(data);
   } catch (error) {
-    res.status(500).json({
-      error: 'Failed to load sku',
-      message: error instanceof Error ? error.message : String(error),
-    });
+    respondWithFailure(res, 'Failed to load sku', error);
   }
 }

From 8aecdf25f7f4ac8194ea6ff42628aa1dbe355d70 Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 14:24:00 -0700
Subject: [PATCH 04/12] feat(commerce-server): standardize route error handling

Every route now fails through one path: domain code and upstream adapters
throw typed CommerceError subclasses, and commerceRoute turns them into
{ error, code, correlationId } responses with an X-Correlation-Id header.

- 502 for Commerce failures, including rejected OAuth client credentials
  (upstream_unauthorized). These concern the server's client_credentials
  token, so they are never reported to the caller as 401/403.
- 503 for missing or unreadable configuration on every route.
- 404 for cart writes against a missing or completed cart, via the existing
  cart-not-found classifier moved into an upstream mapping table.
- 500 only for unexpected errors; detail goes to a host-configurable logger.

Hosts can pass logger and getCorrelationId to the router factories.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/quiet-route-failures.md            |  15 +-
 packages/commerce-server/README.md            |  29 ++-
 .../src/configuration-integration.test.ts     |  20 +-
 .../src/get-order-status.test.ts              |  68 ++++++-
 packages/commerce-server/src/index.ts         |  16 ++
 .../src/lib/commerce/cart-scope.ts            |  10 +-
 .../src/lib/commerce/checkout-subgraph.ts     |  35 ++--
 .../src/lib/commerce/commerce-route.ts        | 113 +++++++++++
 .../src/lib/commerce/config.ts                |  49 +++--
 .../lib/commerce/create-checkout-session.ts   |  26 ++-
 .../src/lib/commerce/errors.ts                | 101 ++++++++++
 .../src/lib/commerce/get-order-status.ts      |  53 ++++--
 .../commerce-server/src/lib/commerce/gql.ts   |  33 +++-
 .../src/lib/commerce/route-failure.ts         |   6 -
 .../src/lib/commerce/upstream-errors.ts       |  50 +++++
 packages/commerce-server/src/router.test.ts   | 178 +++++++++++++++++-
 packages/commerce-server/src/router.ts        |  41 +++-
 .../src/server/api/commerce/cart/POST.ts      | 127 ++++++-------
 .../src/server/api/commerce/cart/[id]/GET.ts  |  65 +++----
 .../api/commerce/cart/[id]/discounts/POST.ts  |  73 ++++---
 .../api/commerce/cart/[id]/items/POST.ts      |  85 ++++-----
 .../cart/[id]/items/[itemId]/DELETE.ts        |  60 +++---
 .../cart/[id]/items/[itemId]/PATCH.ts         |  82 ++++----
 .../src/server/api/commerce/checkout/POST.ts  | 101 +++++-----
 .../src/server/api/commerce/config/GET.ts     |  23 +--
 .../server/api/commerce/order-status/GET.ts   |  44 ++---
 .../src/server/api/commerce/products/GET.ts   |  46 +++--
 .../server/api/commerce/products/[id]/GET.ts  |  59 +++---
 .../src/server/api/commerce/skus/[id]/GET.ts  |  42 ++---
 29 files changed, 1112 insertions(+), 538 deletions(-)
 create mode 100644 packages/commerce-server/src/lib/commerce/commerce-route.ts
 create mode 100644 packages/commerce-server/src/lib/commerce/errors.ts
 delete mode 100644 packages/commerce-server/src/lib/commerce/route-failure.ts
 create mode 100644 packages/commerce-server/src/lib/commerce/upstream-errors.ts

diff --git a/.changeset/quiet-route-failures.md b/.changeset/quiet-route-failures.md
index eb7aad3e..e0222c85 100644
--- a/.changeset/quiet-route-failures.md
+++ b/.changeset/quiet-route-failures.md
@@ -1,5 +1,16 @@
 ---
-'@godaddy/gd-commerce-server': patch
+'@godaddy/gd-commerce-server': minor
 ---
 
-Stop returning the internal error message in 500 responses from the catalog, cart, and checkout routes. These routes now respond with only `{ "error": "<label>" }` and log the underlying error server-side with `console.error`. Hosts that read `message` from these responses should log server-side instead.
+Standardize route error handling. Every failure now responds with `{ error, code, correlationId }` and an `X-Correlation-Id` header, and no longer includes internal error text in a `message` field.
+
+Status codes now reflect the cause:
+
+- 502 for Commerce failures, including rejected OAuth credentials (`upstream_unauthorized`); previously 500.
+- 503 for missing or unreadable configuration on every route; previously 500 everywhere except `/config`.
+- 404 for cart writes against a missing, expired, or completed cart; previously 500.
+- 500 only for unexpected errors.
+
+Hosts can pass `logger` and `getCorrelationId` to the router factories to receive failure detail and reuse their own request ids. In-process helpers throw exported `CommerceError` subclasses. `validateCommerceCartScope` was internal and is replaced by a throwing `assertCommerceCartScope`.
+
+Hosts that read `message` or check for status 500 should switch to `code` and server-side logs.
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index 4a961c22..9fa67049 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -56,4 +56,31 @@ Configure `checkoutReturnUrls` on the router using trusted deployment settings.
 
 Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of `createCheckoutSession()` own their return URLs and must construct or validate them server-side.
 
-A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) and 404 when the Orders API has no such order or the order belongs to another store or channel. Credential and other upstream failures return 500 with a generic body; the detail is logged server-side with `console.error`. In-process callers can check for the exported `InvalidOrderIdError` and `OrderNotFoundError`. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) and 404 when the Orders API has no such order or the order belongs to another store or channel. Token and other Commerce failures return 502 and unreadable configuration returns 503 (see [Errors](#errors)). In-process callers can check for the exported `InvalidOrderIdError` and `OrderNotFoundError`. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+
+## Errors
+
+Every route reports failures the same way. The body is `{ "error": "<customer-facing message>", "code": "<code>", "correlationId": "<id>" }` (order-status also includes `success: false`), and every response carries the same id in an `X-Correlation-Id` header. Bodies never contain upstream messages, configuration details, or credentials.
+
+| Status | `code` | Meaning |
+| --- | --- | --- |
+| 400 | `invalid_request` | Missing or invalid input. |
+| 404 | `not_found` | Missing order or product, or a cart write against a missing, expired, or completed cart. Cart reads keep returning `200 { "cart": null }`. |
+| 409 | `scope_mismatch` | `X-Commerce-Scope` no longer matches the configured store binding. |
+| 502 | `upstream_unauthorized` | Commerce rejected this server's OAuth client or requested scope. It concerns server credentials, not the caller, so it is never reported as 401/403. |
+| 502 | `upstream_error` | Commerce failed, returned an unexpected response, or could not be reached. |
+| 503 | `not_configured` | Configuration is missing or unreadable, or checkout return URLs are not configured. |
+| 500 | `internal_error` | An unexpected error in this package. |
+
+Upstream errors without a specific mapping stay 502; business errors such as invalid discount codes are not yet distinguished. 5xx detail, including upstream status and GraphQL error codes, goes to the logger:
+
+```ts
+createCommerceRouter({
+  configuration,
+  logger: { error: (message, context) => log.error(context, message) },
+  // Use the host's request id when its edge sets one; unsafe or missing ids fall back to a UUID.
+  getCorrelationId: (req) => req.get('x-request-id'),
+});
+```
+
+`createCommerceCatalogRouter` and `createGoDaddyPaymentsRouter` accept the same `{ logger, getCorrelationId }` as their last argument. The logger defaults to `console.error`. In-process helpers throw the exported `CommerceError` subclasses (`InvalidRequestError`, `NotFoundError`, `CommerceNotConfiguredError`, `UpstreamError`).
diff --git a/packages/commerce-server/src/configuration-integration.test.ts b/packages/commerce-server/src/configuration-integration.test.ts
index 18459a18..c478138f 100644
--- a/packages/commerce-server/src/configuration-integration.test.ts
+++ b/packages/commerce-server/src/configuration-integration.test.ts
@@ -96,7 +96,11 @@ it('serves variant product details without querying SKUGroup.status', async ():
     ]);
     const archived = await clientFetch(`${url.replace('/shirt', '/archived-shirt')}?attributeValues=blue`);
     expect(archived.status).toBe(404);
-    expect(await archived.json()).toEqual({ error: 'Product not found' });
+    expect(await archived.json()).toEqual({
+      error: 'Product not found',
+      code: 'not_found',
+      correlationId: archived.headers.get('x-correlation-id'),
+    });
     expect(upstream).toHaveBeenCalledTimes(3);
   } finally {
     await new Promise<void>((resolve, reject) =>
@@ -238,8 +242,8 @@ it.each([undefined, 'https://api.example.com', 'https://api.example.com:8443'])(
 
 it.each([
   ['Order not found', 200, { cart: null }],
-  ['Authentication token expired', 500, { error: 'Failed to load cart' }],
-  ['Database unavailable', 500, { error: 'Failed to load cart' }],
+  ['Authentication token expired', 502, { error: 'Failed to load cart', code: 'upstream_error' }],
+  ['Database unavailable', 502, { error: 'Failed to load cart', code: 'upstream_error' }],
 ] as const)(
   'handles the actual Apollo error envelope for %s',
   async (message, status, body): Promise<void> => {
@@ -276,11 +280,15 @@ it.each([
       if (!address || typeof address === 'string') throw new Error('Expected a listening TCP server');
       const response = await clientFetch(`http://127.0.0.1:${address.port}/api/commerce/cart/completed-cart`);
       expect(response.status).toBe(status);
-      expect(await response.json()).toEqual(body);
-      if (status === 500) {
+      const correlationId = response.headers.get('x-correlation-id');
+      expect(await response.json()).toEqual(status === 200 ? body : { ...body, correlationId });
+      if (status === 502) {
         expect(consoleError).toHaveBeenCalledWith(
           'commerce-server: Failed to load cart',
-          expect.objectContaining({ message: expect.stringContaining(message) }),
+          expect.objectContaining({
+            correlationId,
+            error: expect.objectContaining({ message: expect.stringContaining(message) }),
+          }),
         );
       }
     } finally {
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index 3b94ffd2..9a525859 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -202,7 +202,10 @@ describe('order-status route', () => {
       const response = await clientFetch(
         `http://127.0.0.1:${address.port}/api/commerce/order-status${query}`,
       );
-      return { status: response.status, body: await response.json() };
+      const body = (await response.json()) as Record<string, unknown>;
+      expect(body.correlationId).toBe(response.headers.get('x-correlation-id'));
+      const { correlationId: _correlationId, ...stable } = body;
+      return { status: response.status, body: stable };
     } finally {
       await new Promise<void>((resolve, reject) =>
         server.close((error) => (error ? reject(error) : resolve())),
@@ -223,7 +226,11 @@ describe('order-status route', () => {
     async (query): Promise<void> => {
       await expect(requestOrderStatus(query)).resolves.toEqual({
         status: 400,
-        body: { success: false, error: 'missing or invalid orderId query parameter' },
+        body: {
+          success: false,
+          error: 'missing or invalid orderId query parameter',
+          code: 'invalid_request',
+        },
       });
       expect(upstream).not.toHaveBeenCalled();
     },
@@ -241,29 +248,72 @@ describe('order-status route', () => {
       .mockResolvedValueOnce(orderResponse);
     await expect(requestOrderStatus(`?orderId=${order.id}`)).resolves.toEqual({
       status: 404,
-      body: { success: false, error: 'Order not found' },
+      body: { success: false, error: 'Order not found', code: 'not_found' },
     });
   });
 
   it.each([
-    ['a denied token', [new Response('Invalid scope', { status: 403 })]],
+    [
+      'a token denied the order-read scope',
+      'upstream_unauthorized',
+      [new Response('Invalid scope', { status: 403 })],
+    ],
     [
       'an upstream 500',
+      'upstream_error',
       [
         Response.json({ access_token: 'order-token' }),
         new Response('Private upstream details', { status: 500 }),
       ],
     ],
-    ['an incomplete order', [Response.json({ access_token: 'order-token' }), Response.json({})]],
+    [
+      'an incomplete order',
+      'upstream_error',
+      [Response.json({ access_token: 'order-token' }), Response.json({})],
+    ],
   ])(
-    'returns a generic 500 for %s and logs the detail server-side',
-    async (_case, responses): Promise<void> => {
+    'returns a generic 502 for %s and logs the detail server-side',
+    async (_case, code, responses): Promise<void> => {
       const log = vi.spyOn(console, 'error').mockImplementation((): void => {});
       for (const response of responses) upstream.mockResolvedValueOnce(response);
       const result = await requestOrderStatus(`?orderId=${order.id}`);
-      expect(result).toEqual({ status: 500, body: { success: false, error: 'Failed to get order status' } });
-      expect(log).toHaveBeenCalledWith('order-status: failed to get order status', expect.any(Error));
+      expect(result).toEqual({
+        status: 502,
+        body: { success: false, error: 'Failed to get order status', code },
+      });
+      expect(log).toHaveBeenCalledWith(
+        'commerce-server: Failed to get order status',
+        expect.objectContaining({ httpStatus: 502, code, error: expect.any(Error) }),
+      );
       log.mockRestore();
     },
   );
+
+  it('returns 503 when Commerce is not configured', async (): Promise<void> => {
+    const log = vi.spyOn(console, 'error').mockImplementation((): void => {});
+    vi.stubEnv('GODADDY_STORE_ID', '');
+    const app = express();
+    app.use(
+      '/api/commerce',
+      createGoDaddyPaymentsRouter(createRuntimeCommerceConfiguration({ environment: {} })),
+    );
+    const server = app.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    try {
+      const address = server.address();
+      if (!address || typeof address === 'string') throw new Error('Expected a listening TCP server');
+      const response = await clientFetch(
+        `http://127.0.0.1:${address.port}/api/commerce/order-status?orderId=o-1`,
+      );
+      expect(response.status).toBe(503);
+      expect(await response.json()).toMatchObject({ success: false, code: 'not_configured' });
+      expect(upstream).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllEnvs();
+      log.mockRestore();
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+    }
+  });
 });
diff --git a/packages/commerce-server/src/index.ts b/packages/commerce-server/src/index.ts
index 385a8993..bbcaa57e 100644
--- a/packages/commerce-server/src/index.ts
+++ b/packages/commerce-server/src/index.ts
@@ -4,6 +4,12 @@ export {
   parseCommerceCheckoutConfiguration,
 } from './lib/commerce/checkout-config';
 export type { CheckoutReturnUrls } from './lib/commerce/checkout-return-urls';
+export {
+  CORRELATION_ID_HEADER,
+  type CommerceCorrelationIdResolver,
+  type CommerceErrorLogContext,
+  type CommerceLogger,
+} from './lib/commerce/commerce-route';
 export {
   type CommerceConfig,
   type CommerceConfiguration,
@@ -16,6 +22,15 @@ export {
   type CreateCheckoutSessionParams,
   createCheckoutSession,
 } from './lib/commerce/create-checkout-session';
+export {
+  CommerceError,
+  type CommerceErrorCode,
+  CommerceNotConfiguredError,
+  InvalidRequestError,
+  NotFoundError,
+  ScopeMismatchError,
+  UpstreamError,
+} from './lib/commerce/errors';
 export {
   type CommerceOrderStatus,
   getOrderStatus,
@@ -25,6 +40,7 @@ export {
 } from './lib/commerce/get-order-status';
 export {
   type CommerceRouterFeatures,
+  type CommerceRouterObservabilityOptions,
   type CreateCommerceRouterOptions,
   createCommerceCatalogRouter,
   createCommerceRouter,
diff --git a/packages/commerce-server/src/lib/commerce/cart-scope.ts b/packages/commerce-server/src/lib/commerce/cart-scope.ts
index 46c5382a..8fe07896 100644
--- a/packages/commerce-server/src/lib/commerce/cart-scope.ts
+++ b/packages/commerce-server/src/lib/commerce/cart-scope.ts
@@ -1,7 +1,8 @@
 // SERVER ONLY: uses node:crypto. Browser code receives cartScope from GET /api/commerce/config.
 import { createHash } from 'node:crypto';
-import type { Request, Response } from 'express';
+import type { Request } from 'express';
 import type { CommerceConfig } from './config';
+import { ScopeMismatchError } from './errors';
 
 type CartBinding = Pick<CommerceConfig, 'apiBaseUrl' | 'storeId' | 'channelId' | 'currencyCode'>;
 
@@ -14,9 +15,8 @@ export function getCommerceCartScope(config: CartBinding): string {
 }
 
 /** Existing custom clients may omit the header; managed components always send it. */
-export function validateCommerceCartScope(req: Request, res: Response, config: CartBinding): boolean {
+export function assertCommerceCartScope(req: Request, config: CartBinding): void {
   const suppliedScope: string | string[] | undefined = req.headers?.['x-commerce-scope'];
-  if (suppliedScope === undefined || suppliedScope === getCommerceCartScope(config)) return true;
-  res.status(409).json({ error: 'The connected store changed. Reload the page before continuing.' });
-  return false;
+  if (suppliedScope === undefined || suppliedScope === getCommerceCartScope(config)) return;
+  throw new ScopeMismatchError();
 }
diff --git a/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts b/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts
index 38056d6b..0fdc4dc6 100644
--- a/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts
+++ b/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts
@@ -12,6 +12,7 @@
  * - Existing custom cart: convert your cart into lineItems, then post to the route.
  */
 
+import { CommerceNotConfiguredError, UpstreamError } from './errors';
 import type { Money } from './gql';
 
 /**
@@ -343,7 +344,7 @@ export async function getOAuthAccessToken({
   fetch: fetchImplementation,
 }: OAuthTokenInput): Promise<OAuthTokenResponse> {
   if (!clientId || !clientSecret) {
-    throw new Error('clientId and clientSecret are required');
+    throw new CommerceNotConfiguredError('clientId and clientSecret are required');
   }
 
   const requestFetch = fetchImplementation ?? fetch;
@@ -353,20 +354,32 @@ export async function getOAuthAccessToken({
   body.append('client_secret', clientSecret);
   body.append('scope', scope);
 
-  const response = await requestFetch(new URL('/v2/oauth2/token', apiBaseUrl).toString(), {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/x-www-form-urlencoded',
-    },
-    body: body.toString(),
-    cache: 'no-store',
-  });
+  let response: Response;
+  try {
+    response = await requestFetch(new URL('/v2/oauth2/token', apiBaseUrl).toString(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+      cache: 'no-store',
+    });
+  } catch (cause) {
+    throw new UpstreamError('Access token request could not reach Commerce', { cause, details: { scope } });
+  }
 
   if (!response.ok) {
-    throw new Error(`Failed to get access token: ${response.status} ${response.statusText}`);
+    throw new UpstreamError(`Failed to get access token: ${response.status} ${response.statusText}`, {
+      unauthorized: response.status === 400 || response.status === 401 || response.status === 403,
+      details: { upstreamStatus: response.status, scope },
+    });
   }
 
-  return (await response.json()) as OAuthTokenResponse;
+  try {
+    return (await response.json()) as OAuthTokenResponse;
+  } catch (cause) {
+    throw new UpstreamError('Access token response was not JSON', { cause, details: { scope } });
+  }
 }
 
 export function buildBuyNowCheckoutInput(
diff --git a/packages/commerce-server/src/lib/commerce/commerce-route.ts b/packages/commerce-server/src/lib/commerce/commerce-route.ts
new file mode 100644
index 00000000..25d4634f
--- /dev/null
+++ b/packages/commerce-server/src/lib/commerce/commerce-route.ts
@@ -0,0 +1,113 @@
+// SERVER ONLY: uses node:crypto.
+import { randomUUID } from 'node:crypto';
+import type { Request, Response } from 'express';
+import { CommerceError, type CommerceErrorCode, UpstreamError } from './errors';
+import { classifyUpstreamError } from './upstream-errors';
+
+export interface CommerceErrorLogContext {
+  correlationId: string;
+  method: string;
+  path: string;
+  httpStatus: number;
+  code: CommerceErrorCode;
+  details?: Record<string, unknown>;
+  error: unknown;
+}
+
+/** Receives server-side failure detail that is never sent to the browser. */
+export interface CommerceLogger {
+  error(message: string, context: CommerceErrorLogContext): void;
+}
+
+export const consoleCommerceLogger: CommerceLogger = {
+  error: (message, context): void => console.error(message, context),
+};
+
+/** Returns the host's id for this request (for example one set by its load balancer), if any. */
+export type CommerceCorrelationIdResolver = (req: Request) => string | undefined;
+
+export const CORRELATION_ID_HEADER = 'X-Correlation-Id';
+
+// Ids are echoed into logs and a response header, so reject anything that could forge either.
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+
+export function resolveCorrelationId(req: Request, resolver?: CommerceCorrelationIdResolver): string {
+  const supplied = resolver?.(req);
+  return supplied && CORRELATION_ID_PATTERN.test(supplied) ? supplied : randomUUID();
+}
+
+function correlationIdFor(req: Request, res: Response): string {
+  const existing: unknown = res.locals.commerceCorrelationId;
+  if (typeof existing === 'string') return existing;
+  const correlationId = resolveCorrelationId(req);
+  res.locals.commerceCorrelationId = correlationId;
+  if (!res.headersSent) res.setHeader(CORRELATION_ID_HEADER, correlationId);
+  return correlationId;
+}
+
+function loggerFor(res: Response): CommerceLogger {
+  const logger: unknown = res.locals.commerceLogger;
+  return logger && typeof logger === 'object' && 'error' in logger && typeof logger.error === 'function'
+    ? (logger as CommerceLogger)
+    : consoleCommerceLogger;
+}
+
+/**
+ * The single place Commerce failures become HTTP responses. Typed errors keep their status and
+ * public message; unmapped upstream failures are 502 and anything else is 500. 5xx detail goes
+ * to the configured logger, never into the body.
+ */
+export function sendCommerceError(
+  req: Request,
+  res: Response,
+  label: string,
+  error: unknown,
+  failureFields: Record<string, unknown> = {},
+): void {
+  const resolved: CommerceError | undefined =
+    error instanceof UpstreamError
+      ? classifyUpstreamError(error)
+      : error instanceof CommerceError
+        ? error
+        : undefined;
+  const httpStatus = resolved?.httpStatus ?? 500;
+  const code: CommerceErrorCode = resolved?.code ?? 'internal_error';
+  const correlationId = correlationIdFor(req, res);
+
+  if (httpStatus >= 500) {
+    loggerFor(res).error(`commerce-server: ${label}`, {
+      correlationId,
+      method: req.method,
+      path: req.path,
+      httpStatus,
+      code,
+      ...(resolved?.details ? { details: resolved.details } : {}),
+      error,
+    });
+  }
+
+  if (res.headersSent) return;
+  res
+    .status(httpStatus)
+    .json({ ...failureFields, error: resolved?.publicMessage ?? label, code, correlationId });
+}
+
+export interface CommerceRouteOptions {
+  /** Fields every failure body carries in addition to `error`, `code`, and `correlationId`. */
+  failureFields?: Record<string, unknown>;
+}
+
+/** Wraps a route so thrown errors are answered by `sendCommerceError` with the route's label. */
+export function commerceRoute(
+  label: string,
+  handler: (req: Request, res: Response) => Promise<void>,
+  options: CommerceRouteOptions = {},
+): (req: Request, res: Response) => Promise<void> {
+  return async (req, res): Promise<void> => {
+    try {
+      await handler(req, res);
+    } catch (error) {
+      sendCommerceError(req, res, label, error, options.failureFields);
+    }
+  };
+}
diff --git a/packages/commerce-server/src/lib/commerce/config.ts b/packages/commerce-server/src/lib/commerce/config.ts
index 19381526..009565fa 100644
--- a/packages/commerce-server/src/lib/commerce/config.ts
+++ b/packages/commerce-server/src/lib/commerce/config.ts
@@ -1,6 +1,7 @@
 /** Server-only Commerce configuration. Hosts own secrets and deployment-specific loading. */
 import type { Response } from 'express';
 import { type CommerceCheckoutConfiguration, parseCommerceCheckoutConfiguration } from './checkout-config';
+import { CommerceError, CommerceNotConfiguredError } from './errors';
 
 const DEFAULT_API_BASE_URL = 'https://api.godaddy.com';
 
@@ -41,7 +42,7 @@ function normalizeApiBaseUrl(raw: string): string {
   try {
     url = new URL(raw);
   } catch {
-    throw new Error('Commerce config: apiBaseUrl must be a valid HTTPS origin.');
+    throw new CommerceNotConfiguredError('Commerce config: apiBaseUrl must be a valid HTTPS origin.');
   }
   if (
     url.protocol !== 'https:' ||
@@ -51,7 +52,7 @@ function normalizeApiBaseUrl(raw: string): string {
     url.search ||
     url.hash
   ) {
-    throw new Error(
+    throw new CommerceNotConfiguredError(
       'Commerce config: apiBaseUrl must be an HTTPS origin without credentials, path, query, or fragment.',
     );
   }
@@ -60,7 +61,11 @@ function normalizeApiBaseUrl(raw: string): string {
 
 function requireValue(environment: NodeJS.ProcessEnv, key: string): string {
   const value = environment[key]?.trim();
-  if (!value) throw new Error(`Commerce config: ${key} is missing. Configure it in the server environment.`);
+  if (!value) {
+    throw new CommerceNotConfiguredError(
+      `Commerce config: ${key} is missing. Configure it in the server environment.`,
+    );
+  }
   return value;
 }
 
@@ -89,19 +94,33 @@ export function createRuntimeCommerceConfiguration(
   };
 }
 
-export function commerceConfigurationForResponse(res: Response): CommerceConfiguration {
-  const configuration: unknown = res.locals.commerceConfiguration;
-  if (
-    configuration &&
-    typeof configuration === 'object' &&
-    'read' in configuration &&
-    typeof configuration.read === 'function' &&
-    'readCheckout' in configuration &&
-    typeof configuration.readCheckout === 'function'
-  ) {
-    return configuration as CommerceConfiguration;
+// Host-supplied configurations may throw plain errors (for example a missing secrets file);
+// any failure to read configuration is reported as "not configured", never as a server bug.
+function readOrNotConfigured<T>(read: () => T): T {
+  try {
+    return read();
+  } catch (cause) {
+    if (cause instanceof CommerceError) throw cause;
+    throw new CommerceNotConfiguredError('Commerce configuration could not be read', { cause });
   }
-  return createRuntimeCommerceConfiguration();
+}
+
+export function commerceConfigurationForResponse(res: Response): CommerceConfiguration {
+  const supplied: unknown = res.locals.commerceConfiguration;
+  const configuration: CommerceConfiguration =
+    supplied &&
+    typeof supplied === 'object' &&
+    'read' in supplied &&
+    typeof supplied.read === 'function' &&
+    'readCheckout' in supplied &&
+    typeof supplied.readCheckout === 'function'
+      ? (supplied as CommerceConfiguration)
+      : createRuntimeCommerceConfiguration();
+  return {
+    read: (): CommerceConfig => readOrNotConfigured(() => configuration.read()),
+    readCheckout: (): CommerceCheckoutConfiguration =>
+      readOrNotConfigured(() => configuration.readCheckout()),
+  };
 }
 
 export function readCommerceConfigForResponse(res: Response): CommerceConfig {
diff --git a/packages/commerce-server/src/lib/commerce/create-checkout-session.ts b/packages/commerce-server/src/lib/commerce/create-checkout-session.ts
index a57e8bbc..9af4c88b 100644
--- a/packages/commerce-server/src/lib/commerce/create-checkout-session.ts
+++ b/packages/commerce-server/src/lib/commerce/create-checkout-session.ts
@@ -26,6 +26,7 @@ import {
   getOAuthAccessToken,
 } from './checkout-subgraph';
 import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './config';
+import { InvalidRequestError, UpstreamError } from './errors';
 import { gqlRequest } from './gql';
 
 export interface CreateCheckoutSessionParams {
@@ -167,12 +168,14 @@ export async function createCheckoutSession(
   const { draftOrderId, skuId, quantity, lineItemData, returnUrl, successUrl } = params;
 
   if (!returnUrl || !successUrl) {
-    throw new Error('createCheckoutSession: returnUrl and successUrl are required');
+    throw new InvalidRequestError('createCheckoutSession: returnUrl and successUrl are required');
   }
 
   const checkoutSourceCount = [draftOrderId, skuId, lineItemData].filter(Boolean).length;
   if (checkoutSourceCount !== 1) {
-    throw new Error('createCheckoutSession: exactly one of draftOrderId, skuId, or lineItemData is required');
+    throw new InvalidRequestError(
+      'createCheckoutSession: exactly one of draftOrderId, skuId, or lineItemData is required',
+    );
   }
 
   const {
@@ -266,16 +269,21 @@ export async function createCheckoutSession(
       headers: authorizationHeaders({ accessToken: token.access_token }),
     });
   } catch (error) {
-    throw new Error('Commerce checkout session could not be created', { cause: error });
+    // Not classified further: the cart-not-found rule is evidenced for the order storefront only.
+    throw new UpstreamError('Commerce checkout session could not be created', {
+      cause: error,
+      unauthorized: error instanceof UpstreamError && error.code === 'upstream_unauthorized',
+      details: error instanceof UpstreamError ? error.details : undefined,
+    });
   }
 
   const session = result.createCheckoutSession;
   if (!session?.url || !session.id) {
-    throw new Error('Checkout session was not created');
+    throw new UpstreamError('Checkout session was not created');
   }
 
   if (session.storeId !== storeId || session.channelId !== channelId) {
-    throw new Error(
+    throw new UpstreamError(
       `Checkout session binding mismatch: expected store ${storeId} and channel ${channelId}, received store ${session.storeId ?? 'missing'} and channel ${session.channelId ?? 'missing'}`,
     );
   }
@@ -283,20 +291,20 @@ export async function createCheckoutSession(
   const expectedShipping = lineItemData === undefined && checkoutConfiguration.enableShipping;
   const expectedPromotionCodes: boolean = lineItemData === undefined && enablePromotionCodes;
   if (expectedPromotionCodes && session.enablePromotionCodes !== true) {
-    throw new Error('Checkout session did not enable configured promotion codes');
+    throw new UpstreamError('Checkout session did not enable configured promotion codes');
   }
   if (checkoutConfiguration.enableTaxCollection && session.enableTaxCollection !== true) {
-    throw new Error('Checkout session did not enable configured tax collection');
+    throw new UpstreamError('Checkout session did not enable configured tax collection');
   }
   if (
     expectedShipping &&
     (session.enableShipping !== true || session.enableShippingAddressCollection !== true)
   ) {
-    throw new Error('Checkout session did not enable configured shipping and address collection');
+    throw new UpstreamError('Checkout session did not enable configured shipping and address collection');
   }
 
   if (!session.paymentMethods?.card?.processor) {
-    throw new Error('Checkout session did not configure payment methods.');
+    throw new UpstreamError('Checkout session did not configure payment methods.');
   }
 
   return {
diff --git a/packages/commerce-server/src/lib/commerce/errors.ts b/packages/commerce-server/src/lib/commerce/errors.ts
new file mode 100644
index 00000000..e7c1fc36
--- /dev/null
+++ b/packages/commerce-server/src/lib/commerce/errors.ts
@@ -0,0 +1,101 @@
+/**
+ * Typed failures for the Commerce routes and helpers.
+ *
+ * Domain code throws these; `commerceRoute` is the only place that turns them into HTTP
+ * responses. `message` is internal and only logged. `publicMessage` is safe to show a shopper;
+ * when it is absent the route's failure label is used instead.
+ */
+
+export type CommerceErrorCode =
+  | 'invalid_request'
+  | 'scope_mismatch'
+  | 'not_found'
+  | 'not_configured'
+  | 'upstream_unauthorized'
+  | 'upstream_error'
+  | 'internal_error';
+
+export interface CommerceErrorOptions {
+  cause?: unknown;
+  publicMessage?: string;
+  /** Internal diagnostics for the server log. Never sent to the browser. */
+  details?: Record<string, unknown>;
+}
+
+export class CommerceError extends Error {
+  readonly httpStatus: number;
+  readonly code: CommerceErrorCode;
+  readonly publicMessage?: string;
+  readonly details?: Record<string, unknown>;
+
+  constructor(
+    httpStatus: number,
+    code: CommerceErrorCode,
+    message: string,
+    options: CommerceErrorOptions = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = 'CommerceError';
+    this.httpStatus = httpStatus;
+    this.code = code;
+    this.publicMessage = options.publicMessage;
+    this.details = options.details;
+  }
+}
+
+export interface ClientErrorOptions extends Omit<CommerceErrorOptions, 'publicMessage'> {
+  /** Internal message for in-process callers; defaults to the public message. */
+  message?: string;
+}
+
+export class InvalidRequestError extends CommerceError {
+  constructor(publicMessage: string, { message = publicMessage, ...options }: ClientErrorOptions = {}) {
+    super(400, 'invalid_request', message, { ...options, publicMessage });
+    this.name = 'InvalidRequestError';
+  }
+}
+
+export class ScopeMismatchError extends CommerceError {
+  constructor() {
+    const publicMessage = 'The connected store changed. Reload the page before continuing.';
+    super(409, 'scope_mismatch', publicMessage, { publicMessage });
+    this.name = 'ScopeMismatchError';
+  }
+}
+
+export class NotFoundError extends CommerceError {
+  constructor(publicMessage: string, { message = publicMessage, ...options }: ClientErrorOptions = {}) {
+    super(404, 'not_found', message, { ...options, publicMessage });
+    this.name = 'NotFoundError';
+  }
+}
+
+export class CommerceNotConfiguredError extends CommerceError {
+  constructor(
+    message: string,
+    {
+      publicMessage = 'Commerce configuration is unavailable. Complete the store connection before continuing.',
+      ...options
+    }: CommerceErrorOptions = {},
+  ) {
+    super(503, 'not_configured', message, { ...options, publicMessage });
+    this.name = 'CommerceNotConfiguredError';
+  }
+}
+
+export interface UpstreamErrorOptions extends Omit<CommerceErrorOptions, 'publicMessage'> {
+  /** The upstream rejected this server's own credentials (OAuth client or scope). */
+  unauthorized?: boolean;
+}
+
+/**
+ * Commerce returned a failure, an unexpected response, or could not be reached. Always 502:
+ * even an upstream 401/403 concerns this server's client credentials, not the caller, and
+ * answering 401 would collide with the host's own authentication handling.
+ */
+export class UpstreamError extends CommerceError {
+  constructor(message: string, { unauthorized = false, ...options }: UpstreamErrorOptions = {}) {
+    super(502, unauthorized ? 'upstream_unauthorized' : 'upstream_error', message, options);
+    this.name = 'UpstreamError';
+  }
+}
diff --git a/packages/commerce-server/src/lib/commerce/get-order-status.ts b/packages/commerce-server/src/lib/commerce/get-order-status.ts
index d460e462..cc732262 100644
--- a/packages/commerce-server/src/lib/commerce/get-order-status.ts
+++ b/packages/commerce-server/src/lib/commerce/get-order-status.ts
@@ -4,6 +4,7 @@
  */
 import { authorizationHeaders, getOAuthAccessToken } from './checkout-subgraph';
 import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './config';
+import { InvalidRequestError, NotFoundError, UpstreamError } from './errors';
 import type { Money } from './gql';
 
 /** `CommerceOrderStatus.status` when the Orders API reports no payment status. */
@@ -26,14 +27,16 @@ export interface CommerceOrderStatus {
   lineItems?: unknown[];
 }
 
-export class InvalidOrderIdError extends Error {
+export class InvalidOrderIdError extends InvalidRequestError {
   constructor() {
-    super('getOrderStatus: a valid orderId is required');
+    super('missing or invalid orderId query parameter', {
+      message: 'getOrderStatus: a valid orderId is required',
+    });
     this.name = 'InvalidOrderIdError';
   }
 }
 
-export class OrderNotFoundError extends Error {
+export class OrderNotFoundError extends NotFoundError {
   constructor() {
     super('Order not found');
     this.name = 'OrderNotFoundError';
@@ -74,23 +77,39 @@ export async function getOrderStatus(
     apiBaseUrl,
     scope: 'commerce.order:read',
   });
-  const response = await fetch(
-    new URL(
-      `/v1/commerce/stores/${encodeURIComponent(storeId)}/orders/${encodeURIComponent(orderId)}`,
-      apiBaseUrl,
-    ),
-    {
-      method: 'GET',
-      headers: { ...authorizationHeaders({ accessToken: token.access_token }), Accept: 'application/json' },
-      cache: 'no-store',
-    },
-  );
+  let response: Response;
+  try {
+    response = await fetch(
+      new URL(
+        `/v1/commerce/stores/${encodeURIComponent(storeId)}/orders/${encodeURIComponent(orderId)}`,
+        apiBaseUrl,
+      ),
+      {
+        method: 'GET',
+        headers: { ...authorizationHeaders({ accessToken: token.access_token }), Accept: 'application/json' },
+        cache: 'no-store',
+      },
+    );
+  } catch (cause) {
+    throw new UpstreamError('Order lookup could not reach Commerce', { cause });
+  }
   if (response.status === 404) throw new OrderNotFoundError();
-  if (!response.ok) throw new Error(`Failed to load order: upstream returned ${response.status}`);
+  if (!response.ok) {
+    throw new UpstreamError(`Failed to load order: upstream returned ${response.status}`, {
+      unauthorized: response.status === 401 || response.status === 403,
+      details: { upstreamStatus: response.status },
+    });
+  }
 
-  const data = (await response.json()) as OrderResponse;
+  let data: OrderResponse;
+  try {
+    data = (await response.json()) as OrderResponse;
+  } catch (cause) {
+    throw new UpstreamError('Order lookup returned a non-JSON response', { cause });
+  }
   const order = data?.order;
-  if (!order?.id || !order.context) throw new Error('Order lookup did not return the requested order');
+  if (!order?.id || !order.context)
+    throw new UpstreamError('Order lookup did not return the requested order');
   // Report an order bound to another store or channel as missing so the route doesn't reveal it exists.
   if (order.id !== orderId || order.context.storeId !== storeId || order.context.channelId !== channelId) {
     throw new OrderNotFoundError();
diff --git a/packages/commerce-server/src/lib/commerce/gql.ts b/packages/commerce-server/src/lib/commerce/gql.ts
index 25c36d7e..d77e9b80 100644
--- a/packages/commerce-server/src/lib/commerce/gql.ts
+++ b/packages/commerce-server/src/lib/commerce/gql.ts
@@ -6,6 +6,8 @@
  * isomorphic and safe to import from anywhere.
  */
 
+import { UpstreamError } from './errors';
+
 export type GraphQLVariables = Record<string, unknown>;
 
 export interface GraphQLResponseError {
@@ -32,13 +34,14 @@ export interface GqlRequestOptions<TVariables extends object = GraphQLVariables>
   fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 }
 
+/** `status` is the upstream HTTP status; the route responds with `httpStatus` (502) unless mapped. */
 export class GraphQLErrorWithCodes<
   T extends { message?: string; code?: string; status?: number } = {
     message?: string;
     code?: string;
     status?: number;
   },
-> extends Error {
+> extends UpstreamError {
   constructor(
     public errors: T[],
     public status?: number,
@@ -51,7 +54,14 @@ export class GraphQLErrorWithCodes<
             .filter(Boolean)
             .join('; ');
 
-    super(errorMessage);
+    super(errorMessage, {
+      unauthorized: status === 401 || status === 403,
+      details: {
+        upstreamStatus: status,
+        upstreamCodes: errors.map((error) => error.code).filter(Boolean),
+        upstreamStatuses: errors.map((error) => error.status).filter((value) => typeof value === 'number'),
+      },
+    });
     this.name = 'GraphQLErrorWithCodes';
   }
 
@@ -99,12 +109,17 @@ export async function gqlRequest<TData, TVariables extends object = GraphQLVaria
   requestHeaders.set('Content-Type', 'application/json');
 
   const requestFetch = fetchImplementation ?? fetch;
-  const response = await requestFetch(endpoint, {
-    method: 'POST',
-    headers: requestHeaders,
-    body: JSON.stringify({ query, variables: variables ?? {} }),
-    cache: 'no-store',
-  });
+  let response: Response;
+  try {
+    response = await requestFetch(endpoint, {
+      method: 'POST',
+      headers: requestHeaders,
+      body: JSON.stringify({ query, variables: variables ?? {} }),
+      cache: 'no-store',
+    });
+  } catch (cause) {
+    throw new UpstreamError('GraphQL request could not reach Commerce', { cause, details: { endpoint } });
+  }
 
   let result: GraphQLResponse<TData>;
 
@@ -149,7 +164,7 @@ export async function gqlRequest<TData, TVariables extends object = GraphQLVaria
   }
 
   if (result.data === undefined) {
-    throw new Error('GraphQL response did not include data');
+    throw new UpstreamError('GraphQL response did not include data', { details: { endpoint } });
   }
 
   return result.data;
diff --git a/packages/commerce-server/src/lib/commerce/route-failure.ts b/packages/commerce-server/src/lib/commerce/route-failure.ts
deleted file mode 100644
index a149c878..00000000
--- a/packages/commerce-server/src/lib/commerce/route-failure.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import type { Response } from 'express';
-
-export function respondWithFailure(res: Response, label: string, error: unknown): void {
-  console.error(`commerce-server: ${label}`, error);
-  res.status(500).json({ error: label });
-}
diff --git a/packages/commerce-server/src/lib/commerce/upstream-errors.ts b/packages/commerce-server/src/lib/commerce/upstream-errors.ts
new file mode 100644
index 00000000..ba46c4b6
--- /dev/null
+++ b/packages/commerce-server/src/lib/commerce/upstream-errors.ts
@@ -0,0 +1,50 @@
+/**
+ * Known upstream failures that mean something more specific than "Commerce failed" (502).
+ *
+ * Add a rule only with evidence of how Commerce reports the case, plus a test. Unmatched
+ * upstream errors stay 502; the server log carries their codes and statuses so new rules can
+ * be derived from real responses rather than guessed.
+ */
+import { type CommerceError, NotFoundError, type UpstreamError } from './errors';
+import { GraphQLErrorWithCodes } from './gql';
+
+export function isCartNotFoundError(error: unknown): boolean {
+  if (!(error instanceof GraphQLErrorWithCodes)) {
+    return false;
+  }
+
+  // A transport failure or an unrelated GraphQL error must not erase a saved cart.
+  // A bare HTTP 404 can also mean the upstream endpoint itself is unavailable.
+  const isFailure = (status: number | undefined): boolean =>
+    status !== undefined && status >= 400 && status !== 404 && status !== 410;
+  if (isFailure(error.status) || error.errors.length === 0) return false;
+
+  return error.errors.every(({ code, message, status }): boolean => {
+    if (isFailure(status)) return false;
+    // Orders throws this exact message for absent or non-draft orders; Apollo
+    // supplies its generic code rather than a domain-specific not-found code.
+    if (code === 'INTERNAL_SERVER_ERROR' && message === 'Order not found') return true;
+    if (code && /^(?:DRAFT[_-]?)?(?:ORDER|CART)[_-]?(?:NOT[_-]?FOUND|EXPIRED)$/i.test(code)) return true;
+    if (code && !/^(?:NOT[_-]?FOUND|EXPIRED)$/i.test(code)) return false;
+    return /\b(?:cart|(?:draft[ -])?order)\s+(?:(?:is|was|has)\s+)?(?:not found|expired)\b/i.test(
+      message ?? '',
+    );
+  });
+}
+
+interface UpstreamErrorRule {
+  matches(error: UpstreamError): boolean;
+  toError(error: UpstreamError): CommerceError;
+}
+
+const UPSTREAM_ERROR_RULES: readonly UpstreamErrorRule[] = [
+  {
+    // A completed (paid) draft is reported the same way, so this is "no longer a usable cart".
+    matches: isCartNotFoundError,
+    toError: (error) => new NotFoundError('Cart not found', { cause: error }),
+  },
+];
+
+export function classifyUpstreamError(error: UpstreamError): CommerceError {
+  return UPSTREAM_ERROR_RULES.find((rule) => rule.matches(error))?.toError(error) ?? error;
+}
diff --git a/packages/commerce-server/src/router.test.ts b/packages/commerce-server/src/router.test.ts
index d49fe07b..27be41bb 100644
--- a/packages/commerce-server/src/router.test.ts
+++ b/packages/commerce-server/src/router.test.ts
@@ -177,12 +177,16 @@ describe('Commerce scoped routes', () => {
         throw new Error('Missing channel');
       },
     };
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
     await configHandler({} as Request, res as unknown as Response);
     expect(res.status).toHaveBeenCalledWith(503);
     expect(res.json).toHaveBeenCalledWith({
-      error: expect.any(String),
-      message: 'Missing channel',
+      error: 'Commerce configuration is unavailable. Complete the store connection before continuing.',
+      code: 'not_configured',
+      correlationId: expect.any(String),
     });
+    const [, context] = consoleError.mock.calls[0] ?? [];
+    expect((context as { error: Error }).error.cause).toEqual(new Error('Missing channel'));
   });
 
   it.each([
@@ -296,9 +300,16 @@ describe('Commerce scoped routes', () => {
       { headers: {}, params: { id: 'cart-1' } } as unknown as Request,
       res as unknown as Response,
     );
-    expect(res.status).toHaveBeenCalledWith(500);
-    expect(res.json).toHaveBeenCalledWith({ error: 'Failed to load cart' });
-    expect(consoleError).toHaveBeenCalledWith('commerce-server: Failed to load cart', error);
+    expect(res.status).toHaveBeenCalledWith(502);
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'Failed to load cart',
+      code: expect.stringMatching(/^upstream_(?:error|unauthorized)$/),
+      correlationId: expect.any(String),
+    });
+    expect(consoleError).toHaveBeenCalledWith(
+      'commerce-server: Failed to load cart',
+      expect.objectContaining({ httpStatus: 502, error }),
+    );
   });
 
   it.each([
@@ -369,10 +380,10 @@ describe('Commerce scoped routes', () => {
     ['discounts', applyDiscount, 'Failed to apply discount codes'],
     ['checkout', checkout, 'Failed to create checkout session'],
   ] as const)(
-    'returns a generic 500 and logs the detail for %s',
+    'returns a generic 500 and logs the detail of an unexpected error for %s',
     async (_name, handler, label): Promise<void> => {
       const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
-      const failure = new Error('GraphQL request failed: 502 secret-upstream-detail');
+      const failure = new Error('secret internal detail');
       vi.mocked(gqlRequest).mockRejectedValue(failure);
       vi.mocked(createCheckoutSession).mockRejectedValue(failure);
       const res = response();
@@ -390,10 +401,101 @@ describe('Commerce scoped routes', () => {
       await handler(req, res as unknown as Response);
       expect(res.status).toHaveBeenCalledWith(500);
       expect(res.json).toHaveBeenCalledTimes(1);
-      expect(res.json).toHaveBeenCalledWith({ error: label });
-      expect(consoleError).toHaveBeenCalledWith(`commerce-server: ${label}`, failure);
+      expect(res.json).toHaveBeenCalledWith({
+        error: label,
+        code: 'internal_error',
+        correlationId: expect.any(String),
+      });
+      expect(consoleError).toHaveBeenCalledWith(
+        `commerce-server: ${label}`,
+        expect.objectContaining({ httpStatus: 500, code: 'internal_error', error: failure }),
+      );
+    },
+  );
+
+  it.each([
+    ['products', readProducts, 'Failed to load products'],
+    ['product', readProduct, 'Failed to load product'],
+    ['sku', readSku, 'Failed to load sku'],
+    ['create cart', createCart, 'Failed to create cart'],
+    ['read cart', readCart, 'Failed to load cart'],
+    ['add item', addItem, 'Failed to add line item'],
+    ['update item', updateItem, 'Failed to update line item'],
+    ['delete item', deleteItem, 'Failed to delete line item'],
+    ['discounts', applyDiscount, 'Failed to apply discount codes'],
+    ['checkout', checkout, 'Failed to create checkout session'],
+  ] as const)(
+    'returns 502 without upstream detail for an upstream failure in %s',
+    async (_name, handler, label): Promise<void> => {
+      const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const failure = new GraphQLErrorWithCodes(
+        [{ message: 'secret-upstream-detail', code: 'INTERNAL_SERVER_ERROR' }],
+        500,
+      );
+      vi.mocked(gqlRequest).mockRejectedValue(failure);
+      vi.mocked(createCheckoutSession).mockRejectedValue(failure);
+      const res = response();
+      (res.locals as Record<string, unknown>).commerceCheckoutReturnUrlValidator = (
+        returnUrl?: string,
+        successUrl?: string,
+      ) => ({ returnUrl, successUrl });
+      const req = {
+        ...scopedRequest,
+        body: {
+          ...(scopedRequest.body as object),
+          ...(handler === checkout ? { lineItems: undefined, skuId: 'sku-1' } : {}),
+        },
+      } as unknown as Request;
+      await handler(req, res as unknown as Response);
+      expect(res.status).toHaveBeenCalledWith(502);
+      expect(res.json).toHaveBeenCalledWith({
+        error: label,
+        code: 'upstream_error',
+        correlationId: expect.any(String),
+      });
+      expect(JSON.stringify(vi.mocked(res.json).mock.calls)).not.toContain('secret-upstream-detail');
+      expect(consoleError).toHaveBeenCalledWith(
+        `commerce-server: ${label}`,
+        expect.objectContaining({
+          httpStatus: 502,
+          details: expect.objectContaining({ upstreamStatus: 500, upstreamCodes: ['INTERNAL_SERVER_ERROR'] }),
+        }),
+      );
+    },
+  );
+
+  it.each([
+    ['add item', addItem],
+    ['update item', updateItem],
+    ['delete item', deleteItem],
+    ['discounts', applyDiscount],
+  ] as const)(
+    'returns 404 when %s targets a missing or completed cart',
+    async (_name, handler): Promise<void> => {
+      vi.mocked(gqlRequest).mockRejectedValueOnce(
+        new GraphQLErrorWithCodes([{ code: 'INTERNAL_SERVER_ERROR', message: 'Order not found' }]),
+      );
+      const res = response();
+      await handler(scopedRequest, res as unknown as Response);
+      expect(res.status).toHaveBeenCalledWith(404);
+      expect(res.json).toHaveBeenCalledWith({
+        error: 'Cart not found',
+        code: 'not_found',
+        correlationId: expect.any(String),
+      });
     },
   );
+
+  it('reports an upstream 401 as upstream_unauthorized, not a caller authentication failure', async (): Promise<void> => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(gqlRequest).mockRejectedValueOnce(
+      new GraphQLErrorWithCodes([{ code: 'UNAUTHENTICATED', message: 'Bad client' }], 401),
+    );
+    const res = response();
+    await readProducts(scopedRequest, res as unknown as Response);
+    expect(res.status).toHaveBeenCalledWith(502);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ code: 'upstream_unauthorized' }));
+  });
 });
 
 describe('Commerce router mounting', (): void => {
@@ -436,4 +538,62 @@ describe('Commerce router mounting', (): void => {
       });
     }
   });
+
+  async function requestThroughRouter(
+    router: express.Router,
+    path: string,
+    headers: Record<string, string> = {},
+  ): Promise<globalThis.Response> {
+    const app = express();
+    app.use('/api/commerce', router);
+    const server = app.listen(0);
+    try {
+      const address = server.address() as AddressInfo;
+      return await fetch(`http://127.0.0.1:${address.port}/api/commerce${path}`, { headers });
+    } finally {
+      await new Promise<void>((resolve, reject): void => {
+        server.close((error?: Error): void => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+
+  const failingConfiguration: CommerceConfiguration = {
+    ...configuration,
+    read: (): never => {
+      throw new Error('secret config detail');
+    },
+  };
+
+  it('logs failures through the host logger with the response correlation id', async (): Promise<void> => {
+    const logger = { error: vi.fn() };
+    const result = await requestThroughRouter(
+      createCommerceCatalogRouter(failingConfiguration, { logger }),
+      '/products',
+    );
+    const body = (await result.json()) as { correlationId: string };
+    expect(result.status).toBe(503);
+    expect(result.headers.get('x-correlation-id')).toBe(body.correlationId);
+    expect(JSON.stringify(body)).not.toContain('secret config detail');
+    expect(logger.error).toHaveBeenCalledWith(
+      'commerce-server: Failed to load products',
+      expect.objectContaining({ correlationId: body.correlationId, httpStatus: 503, code: 'not_configured' }),
+    );
+  });
+
+  it.each([
+    ['a valid host id', 'edge-123', 'edge-123'],
+    ['an id with unsafe characters', 'id with spaces; level=error', undefined],
+  ])('uses %s from getCorrelationId when it is safe', async (_case, supplied, expected): Promise<void> => {
+    const result = await requestThroughRouter(
+      createCommerceCatalogRouter(configuration, { getCorrelationId: (req) => req.get('x-request-id') }),
+      '/config',
+      { 'x-request-id': supplied },
+    );
+    const correlationId = result.headers.get('x-correlation-id');
+    if (expected) expect(correlationId).toBe(expected);
+    else expect(correlationId).toMatch(/^[0-9a-f-]{36}$/);
+  });
 });
diff --git a/packages/commerce-server/src/router.ts b/packages/commerce-server/src/router.ts
index ede55f5a..fb91d0bf 100644
--- a/packages/commerce-server/src/router.ts
+++ b/packages/commerce-server/src/router.ts
@@ -3,6 +3,13 @@ import {
   type CheckoutReturnUrls,
   createCheckoutReturnUrlValidator,
 } from './lib/commerce/checkout-return-urls';
+import {
+  CORRELATION_ID_HEADER,
+  type CommerceCorrelationIdResolver,
+  type CommerceLogger,
+  consoleCommerceLogger,
+  resolveCorrelationId,
+} from './lib/commerce/commerce-route';
 import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './lib/commerce/config';
 import cartDiscountPost from './server/api/commerce/cart/[id]/discounts/POST';
 import cartGet from './server/api/commerce/cart/[id]/GET';
@@ -22,7 +29,18 @@ export interface CommerceRouterFeatures {
   payments?: boolean;
 }
 
-export interface CreateCommerceRouterOptions {
+/** Where failure detail is logged and how each request's correlation id is chosen. */
+export interface CommerceRouterObservabilityOptions {
+  /** Receives 5xx failure detail. Defaults to `console.error`. */
+  logger?: CommerceLogger;
+  /**
+   * Returns the host's id for the request, for example `(req) => req.get('x-request-id')` when
+   * the host's edge sets that header. Invalid or missing ids fall back to a random UUID.
+   */
+  getCorrelationId?: CommerceCorrelationIdResolver;
+}
+
+export interface CreateCommerceRouterOptions extends CommerceRouterObservabilityOptions {
   configuration?: CommerceConfiguration;
   features?: CommerceRouterFeatures;
   /** Required to enable browser checkout; never derived from request headers. */
@@ -35,11 +53,17 @@ export function createCommerceRouter(options: CreateCommerceRouterOptions = {}):
   const catalogEnabled: boolean = options.features?.catalog ?? true;
   const paymentsEnabled: boolean = options.features?.payments ?? true;
 
+  const logger: CommerceLogger = options.logger ?? consoleCommerceLogger;
+
   const validateCheckoutReturnUrls = options.checkoutReturnUrls
     ? createCheckoutReturnUrlValidator(options.checkoutReturnUrls)
     : undefined;
 
-  router.use((_req, res, next): void => {
+  router.use((req, res, next): void => {
+    const correlationId: string = resolveCorrelationId(req, options.getCorrelationId);
+    res.locals.commerceCorrelationId = correlationId;
+    res.locals.commerceLogger = logger;
+    res.setHeader(CORRELATION_ID_HEADER, correlationId);
     res.locals.commerceConfiguration = configuration;
     res.locals.commerceCheckoutReturnUrlValidator = validateCheckoutReturnUrls;
     next();
@@ -66,15 +90,24 @@ export function createCommerceRouter(options: CreateCommerceRouterOptions = {}):
   return router;
 }
 
-export function createCommerceCatalogRouter(configuration?: CommerceConfiguration): Router {
-  return createCommerceRouter({ configuration, features: { catalog: true, payments: false } });
+export function createCommerceCatalogRouter(
+  configuration?: CommerceConfiguration,
+  observability: CommerceRouterObservabilityOptions = {},
+): Router {
+  return createCommerceRouter({
+    ...observability,
+    configuration,
+    features: { catalog: true, payments: false },
+  });
 }
 
 export function createGoDaddyPaymentsRouter(
   configuration?: CommerceConfiguration,
   checkoutReturnUrls?: CheckoutReturnUrls,
+  observability: CommerceRouterObservabilityOptions = {},
 ): Router {
   return createCommerceRouter({
+    ...observability,
     configuration,
     checkoutReturnUrls,
     features: { catalog: false, payments: true },
diff --git a/packages/commerce-server/src/server/api/commerce/cart/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/POST.ts
index bbe7be74..0d94b4fb 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/POST.ts
@@ -25,8 +25,10 @@
  *   GraphQL field names like `addDraftOrder` or `orderById`.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
+import { InvalidRequestError, UpstreamError } from '@/lib/commerce/errors';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
 import {
   type AddCartOrderResult,
@@ -41,7 +43,6 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const addCartOrderMutation = `
   mutation AddCartOrder($input: AddDraftOrderInput!) {
@@ -64,78 +65,74 @@ interface CreateCartBody {
   lineItems?: AddToCartItemInput[];
 }
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const body = (req.body ?? {}) as CreateCartBody;
-    const initialItems = Array.isArray(body.lineItems) ? body.lineItems : [];
+async function createCart(req: Request, res: Response): Promise<void> {
+  const body = (req.body ?? {}) as CreateCartBody;
+  const initialItems = Array.isArray(body.lineItems) ? body.lineItems : [];
 
-    // Validate all items BEFORE creating the cart so a bad payload can't
-    // produce an orphaned cart (cart created, item add fails, client never
-    // gets the id). Mirrors the validation in POST /api/commerce/cart/:id/items.
-    for (const item of initialItems) {
-      if (!item.skuId || !item.name || typeof item.quantity !== 'number') {
-        res.status(400).json({
-          error: 'Each lineItem must have skuId, a non-empty name, and a numeric quantity',
-        });
-        return;
-      }
+  // Validate all items BEFORE creating the cart so a bad payload can't
+  // produce an orphaned cart (cart created, item add fails, client never
+  // gets the id). Mirrors the validation in POST /api/commerce/cart/:id/items.
+  for (const item of initialItems) {
+    if (!item.skuId || !item.name || typeof item.quantity !== 'number') {
+      throw new InvalidRequestError(
+        'Each lineItem must have skuId, a non-empty name, and a numeric quantity',
+      );
     }
+  }
 
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, channelId, clientId, apiBaseUrl, currencyCode } = config;
-
-    const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-    const headers = storefrontHeaders({ storeId, clientId });
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, channelId, clientId, apiBaseUrl, currencyCode } = config;
 
-    // Step 1: create an EMPTY cart. Do not pass `lineItems` here — the
-    // `addDraftOrder` mutation expects `CreateDraftLineItemInput` (with
-    // server-priced `totals` + `unitAmount`), which the client cannot
-    // produce. SKU-based adds must go through `addLineItemBySkuId`.
-    const created = await gqlRequest<AddCartOrderResult, AddCartOrderVariables>({
-      endpoint,
-      query: addCartOrderMutation,
-      variables: {
-        input: buildEmptyCartOrderInput({
-          storeId,
-          channelId,
-          owner: config.owner,
-          currencyCode: body.currencyCode ?? currencyCode,
-        }),
-      },
-      headers,
-    });
+  const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+  const headers = storefrontHeaders({ storeId, clientId });
 
-    const newCartId = created.addDraftOrder?.id;
-    if (!newCartId) {
-      res.status(500).json({ error: 'Failed to create cart: missing id in mutation response' });
-      return;
-    }
+  // Step 1: create an EMPTY cart. Do not pass `lineItems` here — the
+  // `addDraftOrder` mutation expects `CreateDraftLineItemInput` (with
+  // server-priced `totals` + `unitAmount`), which the client cannot
+  // produce. SKU-based adds must go through `addLineItemBySkuId`.
+  const created = await gqlRequest<AddCartOrderResult, AddCartOrderVariables>({
+    endpoint,
+    query: addCartOrderMutation,
+    variables: {
+      input: buildEmptyCartOrderInput({
+        storeId,
+        channelId,
+        owner: config.owner,
+        currencyCode: body.currencyCode ?? currencyCode,
+      }),
+    },
+    headers,
+  });
 
-    // Step 2: append each initial SKU one-by-one via `addLineItemBySkuId`.
-    // Sequential, not parallel — same-cart line item adds are not safe to
-    // race on the server side.
-    for (const item of initialItems) {
-      await gqlRequest<AddLineItemBySkuIdResult, AddLineItemBySkuIdVariables>({
-        endpoint,
-        query: addLineItemBySkuIdMutation,
-        variables: { input: buildAddLineItemBySkuIdInput(newCartId, item) },
-        headers,
-      });
-    }
+  const newCartId = created.addDraftOrder?.id;
+  if (!newCartId) {
+    throw new UpstreamError('addDraftOrder response did not include a cart id');
+  }
 
-    // Step 3: re-hydrate the cart and return it under the canonical `cart`
-    // key. Clients always read `data.cart` regardless of which cart route
-    // they called.
-    const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
+  // Step 2: append each initial SKU one-by-one via `addLineItemBySkuId`.
+  // Sequential, not parallel — same-cart line item adds are not safe to
+  // race on the server side.
+  for (const item of initialItems) {
+    await gqlRequest<AddLineItemBySkuIdResult, AddLineItemBySkuIdVariables>({
       endpoint,
-      query: getCartOrderQuery,
-      variables: { id: newCartId },
+      query: addLineItemBySkuIdMutation,
+      variables: { input: buildAddLineItemBySkuIdInput(newCartId, item) },
       headers,
     });
-
-    res.status(201).json({ cart: hydrated.orderById ?? null });
-  } catch (error) {
-    respondWithFailure(res, 'Failed to create cart', error);
   }
+
+  // Step 3: re-hydrate the cart and return it under the canonical `cart`
+  // key. Clients always read `data.cart` regardless of which cart route
+  // they called.
+  const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
+    endpoint,
+    query: getCartOrderQuery,
+    variables: { id: newCartId },
+    headers,
+  });
+
+  res.status(201).json({ cart: hydrated.orderById ?? null });
 }
+
+export default commerceRoute('Failed to create cart', createCart);
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
index ef27b35a..58a2fbb2 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
@@ -16,70 +16,49 @@
  *     and clear the persisted `draftOrderId` when that is the case.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
-import { GraphQLErrorWithCodes, gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
+import { InvalidRequestError } from '@/lib/commerce/errors';
+import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
 import {
   type GetCartOrderResult,
   type GetCartOrderVariables,
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
+import { isCartNotFoundError } from '@/lib/commerce/upstream-errors';
 
-function isCartNotFoundError(error: unknown): boolean {
-  if (!(error instanceof GraphQLErrorWithCodes)) {
-    return false;
+async function readCart(req: Request, res: Response): Promise<void> {
+  const cartId: unknown = req.params.id;
+  if (typeof cartId !== 'string' || !cartId) {
+    throw new InvalidRequestError('Missing cart id');
   }
 
-  // A transport failure or an unrelated GraphQL error must not erase a saved cart.
-  // A bare HTTP 404 can also mean the upstream endpoint itself is unavailable.
-  const isFailure = (status: number | undefined): boolean =>
-    status !== undefined && status >= 400 && status !== 404 && status !== 410;
-  if (isFailure(error.status) || error.errors.length === 0) return false;
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
 
-  return error.errors.every(({ code, message, status }): boolean => {
-    if (isFailure(status)) return false;
-    // Orders throws this exact message for absent or non-draft orders; Apollo
-    // supplies its generic code rather than a domain-specific not-found code.
-    if (code === 'INTERNAL_SERVER_ERROR' && message === 'Order not found') return true;
-    if (code && /^(?:DRAFT[_-]?)?(?:ORDER|CART)[_-]?(?:NOT[_-]?FOUND|EXPIRED)$/i.test(code)) return true;
-    if (code && !/^(?:NOT[_-]?FOUND|EXPIRED)$/i.test(code)) return false;
-    return /\b(?:cart|(?:draft[ -])?order)\s+(?:(?:is|was|has)\s+)?(?:not found|expired)\b/i.test(
-      message ?? '',
-    );
-  });
-}
-
-export default async function handler(req: Request, res: Response): Promise<void> {
+  let data: GetCartOrderResult;
   try {
-    const cartId: unknown = req.params.id;
-    if (typeof cartId !== 'string' || !cartId) {
-      res.status(400).json({ error: 'Missing cart id' });
-      return;
-    }
-
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
-
-    const data = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
+    data = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
       endpoint: orderStorefrontEndpoint({ apiBaseUrl }),
       query: getCartOrderQuery,
       variables: { id: cartId },
       headers: storefrontHeaders({ storeId, clientId }),
     });
-
-    // Normalise to a stable `cart` key so client code never has to know that
-    // the underlying GraphQL field is `orderById`. See docblock at the top
-    // of this file.
-    res.json({ cart: data.orderById ?? null });
   } catch (error) {
     if (isCartNotFoundError(error)) {
       res.status(200).json({ cart: null });
       return;
     }
-
-    respondWithFailure(res, 'Failed to load cart', error);
+    throw error;
   }
+
+  // Normalise to a stable `cart` key so client code never has to know that
+  // the underlying GraphQL field is `orderById`. See docblock at the top
+  // of this file.
+  res.json({ cart: data.orderById ?? null });
 }
+
+export default commerceRoute('Failed to load cart', readCart);
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
index 823012c6..684f39ae 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
@@ -14,8 +14,10 @@
  *   read one shape.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
+import { InvalidRequestError } from '@/lib/commerce/errors';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
 import {
   type ApplyDiscountCodesResult,
@@ -25,7 +27,6 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const applyDiscountCodesMutation = `
   mutation ApplyDiscountCodes($input: ApplyDiscountCodesInput!) {
@@ -39,46 +40,42 @@ interface ApplyDiscountsBody {
   discountCodes?: unknown;
 }
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const cartId: unknown = req.params.id;
-    if (typeof cartId !== 'string' || !cartId) {
-      res.status(400).json({ error: 'Missing cart id' });
-      return;
-    }
+async function applyDiscountCodes(req: Request, res: Response): Promise<void> {
+  const cartId: unknown = req.params.id;
+  if (typeof cartId !== 'string' || !cartId) {
+    throw new InvalidRequestError('Missing cart id');
+  }
 
-    const body = (req.body ?? {}) as ApplyDiscountsBody;
-    const codes = Array.isArray(body.discountCodes)
-      ? body.discountCodes.filter((code): code is string => typeof code === 'string' && code.length > 0)
-      : [];
+  const body = (req.body ?? {}) as ApplyDiscountsBody;
+  const codes = Array.isArray(body.discountCodes)
+    ? body.discountCodes.filter((code): code is string => typeof code === 'string' && code.length > 0)
+    : [];
 
-    if (codes.length === 0) {
-      res.status(400).json({ error: 'discountCodes must be a non-empty string array' });
-      return;
-    }
+  if (codes.length === 0) {
+    throw new InvalidRequestError('discountCodes must be a non-empty string array');
+  }
 
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
-    const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-    const headers = storefrontHeaders({ storeId, clientId });
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
+  const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+  const headers = storefrontHeaders({ storeId, clientId });
 
-    await gqlRequest<ApplyDiscountCodesResult, ApplyDiscountCodesVariables>({
-      endpoint,
-      query: applyDiscountCodesMutation,
-      variables: { input: { orderId: cartId, discountCodes: codes } },
-      headers,
-    });
+  await gqlRequest<ApplyDiscountCodesResult, ApplyDiscountCodesVariables>({
+    endpoint,
+    query: applyDiscountCodesMutation,
+    variables: { input: { orderId: cartId, discountCodes: codes } },
+    headers,
+  });
 
-    const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
-      endpoint,
-      query: getCartOrderQuery,
-      variables: { id: cartId },
-      headers,
-    });
+  const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
+    endpoint,
+    query: getCartOrderQuery,
+    variables: { id: cartId },
+    headers,
+  });
 
-    res.json({ cart: hydrated.orderById ?? null });
-  } catch (error) {
-    respondWithFailure(res, 'Failed to apply discount codes', error);
-  }
+  res.json({ cart: hydrated.orderById ?? null });
 }
+
+export default commerceRoute('Failed to apply discount codes', applyDiscountCodes);
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
index 0c52a11a..5c4be0ae 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
@@ -15,8 +15,10 @@
  *   GET /api/commerce/cart/:id so clients only ever read one shape.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
+import { InvalidRequestError } from '@/lib/commerce/errors';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
 import {
   type AddLineItemBySkuIdResult,
@@ -28,7 +30,6 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const addLineItemBySkuIdMutation = `
   mutation AddLineItemBySkuId($input: AddLineItemInput!) {
@@ -38,51 +39,47 @@ const addLineItemBySkuIdMutation = `
   }
 `;
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const cartId: unknown = req.params.id;
-    if (typeof cartId !== 'string' || !cartId) {
-      res.status(400).json({ error: 'Missing cart id' });
-      return;
-    }
+async function addLineItem(req: Request, res: Response): Promise<void> {
+  const cartId: unknown = req.params.id;
+  if (typeof cartId !== 'string' || !cartId) {
+    throw new InvalidRequestError('Missing cart id');
+  }
 
-    const body = (req.body ?? {}) as Partial<AddToCartItemInput>;
-    if (!body.skuId || !body.name || typeof body.quantity !== 'number') {
-      res.status(400).json({ error: 'Missing required fields: skuId, name, quantity' });
-      return;
-    }
+  const body = (req.body ?? {}) as Partial<AddToCartItemInput>;
+  if (!body.skuId || !body.name || typeof body.quantity !== 'number') {
+    throw new InvalidRequestError('Missing required fields: skuId, name, quantity');
+  }
 
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
-    const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-    const headers = storefrontHeaders({ storeId, clientId });
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
+  const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+  const headers = storefrontHeaders({ storeId, clientId });
 
-    // Mutation only returns the new CartLineItem (no order totals). Discard
-    // it and re-fetch the full cart so the response matches the shape of
-    // GET /api/commerce/cart/:id.
-    await gqlRequest<AddLineItemBySkuIdResult, AddLineItemBySkuIdVariables>({
-      endpoint,
-      query: addLineItemBySkuIdMutation,
-      variables: {
-        input: buildAddLineItemBySkuIdInput(cartId, {
-          skuId: body.skuId,
-          name: body.name,
-          quantity: body.quantity,
-        }),
-      },
-      headers,
-    });
+  // Mutation only returns the new CartLineItem (no order totals). Discard
+  // it and re-fetch the full cart so the response matches the shape of
+  // GET /api/commerce/cart/:id.
+  await gqlRequest<AddLineItemBySkuIdResult, AddLineItemBySkuIdVariables>({
+    endpoint,
+    query: addLineItemBySkuIdMutation,
+    variables: {
+      input: buildAddLineItemBySkuIdInput(cartId, {
+        skuId: body.skuId,
+        name: body.name,
+        quantity: body.quantity,
+      }),
+    },
+    headers,
+  });
 
-    const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
-      endpoint,
-      query: getCartOrderQuery,
-      variables: { id: cartId },
-      headers,
-    });
+  const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
+    endpoint,
+    query: getCartOrderQuery,
+    variables: { id: cartId },
+    headers,
+  });
 
-    res.status(201).json({ cart: hydrated.orderById ?? null });
-  } catch (error) {
-    respondWithFailure(res, 'Failed to add line item', error);
-  }
+  res.status(201).json({ cart: hydrated.orderById ?? null });
 }
+
+export default commerceRoute('Failed to add line item', addLineItem);
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
index c35457c1..5715596f 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
@@ -11,8 +11,10 @@
  *   GET /api/commerce/cart/:id so clients only ever read one shape.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
+import { InvalidRequestError } from '@/lib/commerce/errors';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
 import {
   type DeleteLineItemByIdResult,
@@ -22,7 +24,6 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const deleteLineItemByIdMutation = `
   mutation DeleteLineItemById($id: ID!, $orderId: ID!) {
@@ -30,37 +31,34 @@ const deleteLineItemByIdMutation = `
   }
 `;
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const cartId: unknown = req.params.id;
-    const itemId: unknown = req.params.itemId;
-    if (typeof cartId !== 'string' || !cartId || typeof itemId !== 'string' || !itemId) {
-      res.status(400).json({ error: 'Missing cart id or item id' });
-      return;
-    }
+async function deleteLineItem(req: Request, res: Response): Promise<void> {
+  const cartId: unknown = req.params.id;
+  const itemId: unknown = req.params.itemId;
+  if (typeof cartId !== 'string' || !cartId || typeof itemId !== 'string' || !itemId) {
+    throw new InvalidRequestError('Missing cart id or item id');
+  }
 
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
-    const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-    const headers = storefrontHeaders({ storeId, clientId });
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
+  const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+  const headers = storefrontHeaders({ storeId, clientId });
 
-    await gqlRequest<DeleteLineItemByIdResult, DeleteLineItemByIdVariables>({
-      endpoint,
-      query: deleteLineItemByIdMutation,
-      variables: { id: itemId, orderId: cartId },
-      headers,
-    });
+  await gqlRequest<DeleteLineItemByIdResult, DeleteLineItemByIdVariables>({
+    endpoint,
+    query: deleteLineItemByIdMutation,
+    variables: { id: itemId, orderId: cartId },
+    headers,
+  });
 
-    const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
-      endpoint,
-      query: getCartOrderQuery,
-      variables: { id: cartId },
-      headers,
-    });
+  const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
+    endpoint,
+    query: getCartOrderQuery,
+    variables: { id: cartId },
+    headers,
+  });
 
-    res.json({ cart: hydrated.orderById ?? null });
-  } catch (error) {
-    respondWithFailure(res, 'Failed to delete line item', error);
-  }
+  res.json({ cart: hydrated.orderById ?? null });
 }
+
+export default commerceRoute('Failed to delete line item', deleteLineItem);
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
index a68e3092..1af9cb32 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
@@ -14,8 +14,10 @@
  *   clients only ever read one shape.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
+import { InvalidRequestError } from '@/lib/commerce/errors';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
 import {
   type GetCartOrderResult,
@@ -26,7 +28,6 @@ import {
   type UpdateLineItemByIdResult,
   type UpdateLineItemByIdVariables,
 } from '@/lib/commerce/order-subgraph';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const updateLineItemByIdMutation = `
   mutation UpdateLineItemById($input: UpdateLineItemByIdInput!) {
@@ -38,49 +39,46 @@ const updateLineItemByIdMutation = `
 
 type UpdateLineItemBody = Omit<UpdateLineItemByIdInput, 'id' | 'orderId'>;
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const cartId: unknown = req.params.id;
-    const itemId: unknown = req.params.itemId;
-    if (typeof cartId !== 'string' || !cartId || typeof itemId !== 'string' || !itemId) {
-      res.status(400).json({ error: 'Missing cart id or item id' });
-      return;
-    }
+async function updateLineItem(req: Request, res: Response): Promise<void> {
+  const cartId: unknown = req.params.id;
+  const itemId: unknown = req.params.itemId;
+  if (typeof cartId !== 'string' || !cartId || typeof itemId !== 'string' || !itemId) {
+    throw new InvalidRequestError('Missing cart id or item id');
+  }
 
-    const body = (req.body ?? {}) as UpdateLineItemBody;
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
-    const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-    const headers = storefrontHeaders({ storeId, clientId });
+  const body = (req.body ?? {}) as UpdateLineItemBody;
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
+  const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+  const headers = storefrontHeaders({ storeId, clientId });
 
-    await gqlRequest<UpdateLineItemByIdResult, UpdateLineItemByIdVariables>({
-      endpoint,
-      query: updateLineItemByIdMutation,
-      variables: {
-        input: {
-          id: itemId,
-          orderId: cartId,
-          name: body.name,
-          quantity: body.quantity,
-          fulfillmentMode: body.fulfillmentMode,
-          status: body.status,
-          type: body.type,
-          details: body.details,
-        },
+  await gqlRequest<UpdateLineItemByIdResult, UpdateLineItemByIdVariables>({
+    endpoint,
+    query: updateLineItemByIdMutation,
+    variables: {
+      input: {
+        id: itemId,
+        orderId: cartId,
+        name: body.name,
+        quantity: body.quantity,
+        fulfillmentMode: body.fulfillmentMode,
+        status: body.status,
+        type: body.type,
+        details: body.details,
       },
-      headers,
-    });
+    },
+    headers,
+  });
 
-    const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
-      endpoint,
-      query: getCartOrderQuery,
-      variables: { id: cartId },
-      headers,
-    });
+  const hydrated = await gqlRequest<GetCartOrderResult, GetCartOrderVariables>({
+    endpoint,
+    query: getCartOrderQuery,
+    variables: { id: cartId },
+    headers,
+  });
 
-    res.json({ cart: hydrated.orderById ?? null });
-  } catch (error) {
-    respondWithFailure(res, 'Failed to update line item', error);
-  }
+  res.json({ cart: hydrated.orderById ?? null });
 }
+
+export default commerceRoute('Failed to update line item', updateLineItem);
diff --git a/packages/commerce-server/src/server/api/commerce/checkout/POST.ts b/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
index bd6d7b31..c6a4c6ae 100644
--- a/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
@@ -37,74 +37,67 @@
  * return a `redirectUrl` field.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
 import type { CheckoutReturnUrlValidator } from '@/lib/commerce/checkout-return-urls';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, commerceConfigurationForResponse } from '@/lib/commerce/config';
-
 import {
   type CreateCheckoutSessionParams,
   createCheckoutSession,
 } from '@/lib/commerce/create-checkout-session';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
+import { CommerceNotConfiguredError, InvalidRequestError } from '@/lib/commerce/errors';
 
 type CheckoutBody = Partial<CreateCheckoutSessionParams>;
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const configuration = commerceConfigurationForResponse(res);
-    const body = (req.body ?? {}) as CheckoutBody;
-    const { draftOrderId, skuId, quantity, lineItemData, returnUrl, successUrl } = body;
+async function createCheckout(req: Request, res: Response): Promise<void> {
+  const configuration = commerceConfigurationForResponse(res);
+  const body = (req.body ?? {}) as CheckoutBody;
+  const { draftOrderId, skuId, quantity, lineItemData, returnUrl, successUrl } = body;
 
-    if (lineItemData !== undefined) {
-      res.status(400).json({ error: 'Non-catalog checkout must be created by the server.' });
-      return;
-    }
+  if (lineItemData !== undefined) {
+    throw new InvalidRequestError('Non-catalog checkout must be created by the server.');
+  }
 
-    const checkoutSourceCount = [draftOrderId, skuId].filter(Boolean).length;
-    if (
-      checkoutSourceCount !== 1 ||
-      [draftOrderId, skuId].some(
-        (value) => value !== undefined && (typeof value !== 'string' || !value.trim()),
-      )
-    ) {
-      res.status(400).json({ error: 'exactly one non-empty draftOrderId or skuId is required' });
-      return;
-    }
+  const checkoutSourceCount = [draftOrderId, skuId].filter(Boolean).length;
+  if (
+    checkoutSourceCount !== 1 ||
+    [draftOrderId, skuId].some((value) => value !== undefined && (typeof value !== 'string' || !value.trim()))
+  ) {
+    throw new InvalidRequestError('exactly one non-empty draftOrderId or skuId is required');
+  }
 
-    if (quantity !== undefined && (!Number.isSafeInteger(quantity) || quantity < 1)) {
-      res.status(400).json({ error: 'quantity must be a positive whole number' });
-      return;
-    }
+  if (quantity !== undefined && (!Number.isSafeInteger(quantity) || quantity < 1)) {
+    throw new InvalidRequestError('quantity must be a positive whole number');
+  }
 
-    if (req.headers?.['x-commerce-scope'] !== undefined) {
-      const config: CommerceConfig = configuration.read();
-      if (!validateCommerceCartScope(req, res, config)) return;
-    }
+  if (req.headers?.['x-commerce-scope'] !== undefined) {
+    const config: CommerceConfig = configuration.read();
+    assertCommerceCartScope(req, config);
+  }
 
-    const validateReturnUrls: CheckoutReturnUrlValidator | undefined =
-      res.locals.commerceCheckoutReturnUrlValidator;
-    if (!validateReturnUrls) {
-      res.status(503).json({ error: 'Checkout return destinations are not configured.' });
-      return;
-    }
-    const destinations = validateReturnUrls(returnUrl, successUrl);
-    if (!destinations) {
-      res.status(400).json({ error: 'Checkout return destinations are not allowed.' });
-      return;
-    }
+  const validateReturnUrls: CheckoutReturnUrlValidator | undefined =
+    res.locals.commerceCheckoutReturnUrlValidator;
+  if (!validateReturnUrls) {
+    throw new CommerceNotConfiguredError('Checkout return URLs are not configured on the router.', {
+      publicMessage: 'Checkout return destinations are not configured.',
+    });
+  }
+  const destinations = validateReturnUrls(returnUrl, successUrl);
+  if (!destinations) {
+    throw new InvalidRequestError('Checkout return destinations are not allowed.');
+  }
 
-    const session = await createCheckoutSession(
-      {
-        draftOrderId,
-        skuId,
-        quantity,
-        ...destinations,
-      },
-      configuration,
-    );
+  const session = await createCheckoutSession(
+    {
+      draftOrderId,
+      skuId,
+      quantity,
+      ...destinations,
+    },
+    configuration,
+  );
 
-    res.status(200).json(session);
-  } catch (error) {
-    respondWithFailure(res, 'Failed to create checkout session', error);
-  }
+  res.status(200).json(session);
 }
+
+export default commerceRoute('Failed to create checkout session', createCheckout);
diff --git a/packages/commerce-server/src/server/api/commerce/config/GET.ts b/packages/commerce-server/src/server/api/commerce/config/GET.ts
index 3169634f..8c5f9df7 100644
--- a/packages/commerce-server/src/server/api/commerce/config/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/config/GET.ts
@@ -5,21 +5,16 @@
  */
 import type { Request, Response } from 'express';
 import { getCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, commerceConfigurationForResponse } from '@/lib/commerce/config';
 
-export default async function handler(_req: Request, res: Response): Promise<void> {
+async function readPublicConfig(_req: Request, res: Response): Promise<void> {
   res.setHeader('Cache-Control', 'no-store');
-  try {
-    const configuration = commerceConfigurationForResponse(res);
-    const config: CommerceConfig = configuration.read();
-    res.json({
-      cartScope: getCommerceCartScope(config),
-      currencyCode: config.currencyCode,
-    });
-  } catch (cause: unknown) {
-    res.status(503).json({
-      error: 'Commerce configuration is unavailable. Complete the store connection before continuing.',
-      message: cause instanceof Error ? cause.message : 'Invalid Commerce configuration.',
-    });
-  }
+  const config: CommerceConfig = commerceConfigurationForResponse(res).read();
+  res.json({
+    cartScope: getCommerceCartScope(config),
+    currencyCode: config.currencyCode,
+  });
 }
+
+export default commerceRoute('Failed to load Commerce configuration', readPublicConfig);
diff --git a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
index 6de46885..fb1fe494 100644
--- a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
@@ -16,37 +16,27 @@
  *       order.status is the payment status returned by the authorized Orders API.
  *   400 missing, blank, padded, `.` or `..` orderId
  *   404 no order with that id in the configured store and channel
- *   500 credential, upstream, or configuration failure
+ *   502 Commerce or token failure (`code: upstream_error | upstream_unauthorized`)
+ *   503 Commerce is not configured
+ *   500 unexpected server failure
+ * Failure bodies are { success: false, error, code, correlationId }.
  * The host must authorize the caller's access to the requested order.
  */
 import type { Request, Response } from 'express';
-
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { commerceConfigurationForResponse } from '@/lib/commerce/config';
-import { getOrderStatus, InvalidOrderIdError, OrderNotFoundError } from '@/lib/commerce/get-order-status';
-
-const invalidOrderIdBody = { success: false, error: 'missing or invalid orderId query parameter' };
-
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const { orderId } = req.query;
-    if (!orderId || typeof orderId !== 'string') {
-      res.status(400).json(invalidOrderIdBody);
-      return;
-    }
+import { getOrderStatus, InvalidOrderIdError } from '@/lib/commerce/get-order-status';
 
-    const order = await getOrderStatus(orderId, commerceConfigurationForResponse(res));
-    res.status(200).json({ success: true, order });
-  } catch (error) {
-    if (error instanceof InvalidOrderIdError) {
-      res.status(400).json(invalidOrderIdBody);
-      return;
-    }
-    if (error instanceof OrderNotFoundError) {
-      res.status(404).json({ success: false, error: 'Order not found' });
-      return;
-    }
-    // The detail can name upstream statuses, credentials, or configuration, so it stays server-side.
-    console.error('order-status: failed to get order status', error);
-    res.status(500).json({ success: false, error: 'Failed to get order status' });
+async function readOrderStatus(req: Request, res: Response): Promise<void> {
+  const { orderId } = req.query;
+  if (!orderId || typeof orderId !== 'string') {
+    throw new InvalidOrderIdError();
   }
+
+  const order = await getOrderStatus(orderId, commerceConfigurationForResponse(res));
+  res.status(200).json({ success: true, order });
 }
+
+export default commerceRoute('Failed to get order status', readOrderStatus, {
+  failureFields: { success: false },
+});
diff --git a/packages/commerce-server/src/server/api/commerce/products/GET.ts b/packages/commerce-server/src/server/api/commerce/products/GET.ts
index 550c4bab..34e27e86 100644
--- a/packages/commerce-server/src/server/api/commerce/products/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/products/GET.ts
@@ -18,16 +18,16 @@
  * `data` field. Use the helpers in lib/commerce/catalog-subgraph.ts to extract view-model fields.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
 import {
   buildSkuGroupsVariables,
   catalogStorefrontEndpoint,
   type SkuGroupsResult,
   type SkuGroupsVariables,
 } from '@/lib/commerce/catalog-subgraph';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 // Cards use group pricing/media and SKU identity/inventory for quick-add.
 // Nested SKU price money fields would exceed the catalog API's depth limit of 10.
@@ -131,29 +131,27 @@ function asNumber(value: unknown): number | undefined {
   return Number.isFinite(n) ? n : undefined;
 }
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
+async function listProducts(req: Request, res: Response): Promise<void> {
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
 
-    const variables = buildSkuGroupsVariables({
-      first: asNumber(req.query.first) ?? 24,
-      after: typeof req.query.after === 'string' ? req.query.after : undefined,
-      searchQuery: typeof req.query.searchQuery === 'string' ? req.query.searchQuery : undefined,
-      productIds: asStringArray(req.query.productIds),
-      categoryIds: asStringArray(req.query.categoryIds),
-    });
+  const variables = buildSkuGroupsVariables({
+    first: asNumber(req.query.first) ?? 24,
+    after: typeof req.query.after === 'string' ? req.query.after : undefined,
+    searchQuery: typeof req.query.searchQuery === 'string' ? req.query.searchQuery : undefined,
+    productIds: asStringArray(req.query.productIds),
+    categoryIds: asStringArray(req.query.categoryIds),
+  });
 
-    const data = await gqlRequest<SkuGroupsResult, SkuGroupsVariables>({
-      endpoint: catalogStorefrontEndpoint({ storeId, apiBaseUrl }),
-      query: skuGroupsQuery,
-      variables,
-      headers: storefrontHeaders({ storeId, clientId }),
-    });
+  const data = await gqlRequest<SkuGroupsResult, SkuGroupsVariables>({
+    endpoint: catalogStorefrontEndpoint({ storeId, apiBaseUrl }),
+    query: skuGroupsQuery,
+    variables,
+    headers: storefrontHeaders({ storeId, clientId }),
+  });
 
-    res.json(data);
-  } catch (error) {
-    respondWithFailure(res, 'Failed to load products', error);
-  }
+  res.json(data);
 }
+
+export default commerceRoute('Failed to load products', listProducts);
diff --git a/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts b/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts
index 4954aa18..7abf1d7b 100644
--- a/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/products/[id]/GET.ts
@@ -16,7 +16,7 @@
  * Response: { skuGroup: SKUGroup } for an active product, otherwise 404.
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
 import {
   buildSkuGroupVariables,
   catalogStorefrontEndpoint,
@@ -24,9 +24,10 @@ import {
   type SkuGroupsResult,
   type SkuGroupVariables,
 } from '@/lib/commerce/catalog-subgraph';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
+import { InvalidRequestError, NotFoundError } from '@/lib/commerce/errors';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 type ProductDetailsResult = SkuGroupResult & { activeSkuGroups?: SkuGroupsResult['skuGroups'] };
 
@@ -126,38 +127,34 @@ function asNumber(value: unknown): number | undefined {
   return Number.isFinite(n) ? n : undefined;
 }
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const productId: unknown = req.params.id;
-    if (typeof productId !== 'string' || !productId) {
-      res.status(400).json({ error: 'Missing product id' });
-      return;
-    }
-
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
+async function readProduct(req: Request, res: Response): Promise<void> {
+  const productId: unknown = req.params.id;
+  if (typeof productId !== 'string' || !productId) {
+    throw new InvalidRequestError('Missing product id');
+  }
 
-    const variables = buildSkuGroupVariables({
-      productId,
-      selectedAttributeValues: asStringArray(req.query.attributeValues),
-      skuGroupFirst: asNumber(req.query.skuGroupFirst),
-    });
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
 
-    const data = await gqlRequest<ProductDetailsResult, SkuGroupVariables>({
-      endpoint: catalogStorefrontEndpoint({ storeId, apiBaseUrl }),
-      query: skuGroupQuery,
-      variables,
-      headers: storefrontHeaders({ storeId, clientId }),
-    });
+  const variables = buildSkuGroupVariables({
+    productId,
+    selectedAttributeValues: asStringArray(req.query.attributeValues),
+    skuGroupFirst: asNumber(req.query.skuGroupFirst),
+  });
 
-    if (!data.skuGroup || !data.activeSkuGroups?.edges?.some((edge) => edge?.node?.id === productId)) {
-      res.status(404).json({ error: 'Product not found' });
-      return;
-    }
+  const data = await gqlRequest<ProductDetailsResult, SkuGroupVariables>({
+    endpoint: catalogStorefrontEndpoint({ storeId, apiBaseUrl }),
+    query: skuGroupQuery,
+    variables,
+    headers: storefrontHeaders({ storeId, clientId }),
+  });
 
-    res.json({ skuGroup: data.skuGroup });
-  } catch (error) {
-    respondWithFailure(res, 'Failed to load product', error);
+  if (!data.skuGroup || !data.activeSkuGroups?.edges?.some((edge) => edge?.node?.id === productId)) {
+    throw new NotFoundError('Product not found');
   }
+
+  res.json({ skuGroup: data.skuGroup });
 }
+
+export default commerceRoute('Failed to load product', readProduct);
diff --git a/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts b/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts
index f736e3dd..e19a187a 100644
--- a/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/skus/[id]/GET.ts
@@ -8,15 +8,16 @@
  * Response: { sku: SKU | null }
  */
 import type { Request, Response } from 'express';
-import { validateCommerceCartScope } from '@/lib/commerce/cart-scope';
+import { assertCommerceCartScope } from '@/lib/commerce/cart-scope';
 import {
   catalogStorefrontEndpoint,
   type SkuResult,
   type SkuVariables,
 } from '@/lib/commerce/catalog-subgraph';
+import { commerceRoute } from '@/lib/commerce/commerce-route';
 import { type CommerceConfig, readCommerceConfigForResponse } from '@/lib/commerce/config';
+import { InvalidRequestError } from '@/lib/commerce/errors';
 import { gqlRequest, storefrontHeaders } from '@/lib/commerce/gql';
-import { respondWithFailure } from '@/lib/commerce/route-failure';
 
 const skuQuery = `
   query Sku($id: String!) {
@@ -75,27 +76,24 @@ const skuQuery = `
   }
 `;
 
-export default async function handler(req: Request, res: Response): Promise<void> {
-  try {
-    const skuId: unknown = req.params.id;
-    if (typeof skuId !== 'string' || !skuId) {
-      res.status(400).json({ error: 'Missing sku id' });
-      return;
-    }
+async function readSku(req: Request, res: Response): Promise<void> {
+  const skuId: unknown = req.params.id;
+  if (typeof skuId !== 'string' || !skuId) {
+    throw new InvalidRequestError('Missing sku id');
+  }
 
-    const config: CommerceConfig = readCommerceConfigForResponse(res);
-    if (!validateCommerceCartScope(req, res, config)) return;
-    const { storeId, clientId, apiBaseUrl } = config;
+  const config: CommerceConfig = readCommerceConfigForResponse(res);
+  assertCommerceCartScope(req, config);
+  const { storeId, clientId, apiBaseUrl } = config;
 
-    const data = await gqlRequest<SkuResult, SkuVariables>({
-      endpoint: catalogStorefrontEndpoint({ storeId, apiBaseUrl }),
-      query: skuQuery,
-      variables: { id: skuId },
-      headers: storefrontHeaders({ storeId, clientId }),
-    });
+  const data = await gqlRequest<SkuResult, SkuVariables>({
+    endpoint: catalogStorefrontEndpoint({ storeId, apiBaseUrl }),
+    query: skuQuery,
+    variables: { id: skuId },
+    headers: storefrontHeaders({ storeId, clientId }),
+  });
 
-    res.json(data);
-  } catch (error) {
-    respondWithFailure(res, 'Failed to load sku', error);
-  }
+  res.json(data);
 }
+
+export default commerceRoute('Failed to load sku', readSku);

From 01525cc6480fd5989a186207c09b9a5b0f5d5685 Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 15:28:37 -0700
Subject: [PATCH 05/12] fix(commerce-server): drop the X-Correlation-Id
 response header

The header name was not an established convention in this repo or in the
Commerce APIs. Keep the id in failure bodies and logs only; a response header
can be added once its name is designed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/quiet-route-failures.md                       | 2 +-
 packages/commerce-server/README.md                       | 2 +-
 .../src/configuration-integration.test.ts                | 7 ++++---
 packages/commerce-server/src/get-order-status.test.ts    | 2 +-
 packages/commerce-server/src/index.ts                    | 9 ++++-----
 .../commerce-server/src/lib/commerce/commerce-route.ts   | 5 +----
 packages/commerce-server/src/router.test.ts              | 9 ++++++---
 packages/commerce-server/src/router.ts                   | 2 --
 8 files changed, 18 insertions(+), 20 deletions(-)

diff --git a/.changeset/quiet-route-failures.md b/.changeset/quiet-route-failures.md
index e0222c85..f858697a 100644
--- a/.changeset/quiet-route-failures.md
+++ b/.changeset/quiet-route-failures.md
@@ -2,7 +2,7 @@
 '@godaddy/gd-commerce-server': minor
 ---
 
-Standardize route error handling. Every failure now responds with `{ error, code, correlationId }` and an `X-Correlation-Id` header, and no longer includes internal error text in a `message` field.
+Standardize route error handling. Every failure now responds with `{ error, code, correlationId }` and no longer includes internal error text in a `message` field.
 
 Status codes now reflect the cause:
 
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index 9fa67049..19257b7d 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -60,7 +60,7 @@ A return from hosted checkout is not proof of payment. The order-status route us
 
 ## Errors
 
-Every route reports failures the same way. The body is `{ "error": "<customer-facing message>", "code": "<code>", "correlationId": "<id>" }` (order-status also includes `success: false`), and every response carries the same id in an `X-Correlation-Id` header. Bodies never contain upstream messages, configuration details, or credentials.
+Every route reports failures the same way. The body is `{ "error": "<customer-facing message>", "code": "<code>", "correlationId": "<id>" }` (order-status also includes `success: false`). The same id is passed to the logger. Bodies never contain upstream messages, configuration details, or credentials.
 
 | Status | `code` | Meaning |
 | --- | --- | --- |
diff --git a/packages/commerce-server/src/configuration-integration.test.ts b/packages/commerce-server/src/configuration-integration.test.ts
index c478138f..0ba445ca 100644
--- a/packages/commerce-server/src/configuration-integration.test.ts
+++ b/packages/commerce-server/src/configuration-integration.test.ts
@@ -99,7 +99,7 @@ it('serves variant product details without querying SKUGroup.status', async ():
     expect(await archived.json()).toEqual({
       error: 'Product not found',
       code: 'not_found',
-      correlationId: archived.headers.get('x-correlation-id'),
+      correlationId: expect.any(String),
     });
     expect(upstream).toHaveBeenCalledTimes(3);
   } finally {
@@ -280,8 +280,9 @@ it.each([
       if (!address || typeof address === 'string') throw new Error('Expected a listening TCP server');
       const response = await clientFetch(`http://127.0.0.1:${address.port}/api/commerce/cart/completed-cart`);
       expect(response.status).toBe(status);
-      const correlationId = response.headers.get('x-correlation-id');
-      expect(await response.json()).toEqual(status === 200 ? body : { ...body, correlationId });
+      const json = (await response.json()) as { correlationId?: string };
+      const correlationId = json.correlationId;
+      expect(json).toEqual(status === 200 ? body : { ...body, correlationId: expect.any(String) });
       if (status === 502) {
         expect(consoleError).toHaveBeenCalledWith(
           'commerce-server: Failed to load cart',
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index 9a525859..2a37870f 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -203,7 +203,7 @@ describe('order-status route', () => {
         `http://127.0.0.1:${address.port}/api/commerce/order-status${query}`,
       );
       const body = (await response.json()) as Record<string, unknown>;
-      expect(body.correlationId).toBe(response.headers.get('x-correlation-id'));
+      expect(body.correlationId).toEqual(expect.any(String));
       const { correlationId: _correlationId, ...stable } = body;
       return { status: response.status, body: stable };
     } finally {
diff --git a/packages/commerce-server/src/index.ts b/packages/commerce-server/src/index.ts
index bbcaa57e..ba0aec5c 100644
--- a/packages/commerce-server/src/index.ts
+++ b/packages/commerce-server/src/index.ts
@@ -4,11 +4,10 @@ export {
   parseCommerceCheckoutConfiguration,
 } from './lib/commerce/checkout-config';
 export type { CheckoutReturnUrls } from './lib/commerce/checkout-return-urls';
-export {
-  CORRELATION_ID_HEADER,
-  type CommerceCorrelationIdResolver,
-  type CommerceErrorLogContext,
-  type CommerceLogger,
+export type {
+  CommerceCorrelationIdResolver,
+  CommerceErrorLogContext,
+  CommerceLogger,
 } from './lib/commerce/commerce-route';
 export {
   type CommerceConfig,
diff --git a/packages/commerce-server/src/lib/commerce/commerce-route.ts b/packages/commerce-server/src/lib/commerce/commerce-route.ts
index 25d4634f..591443ce 100644
--- a/packages/commerce-server/src/lib/commerce/commerce-route.ts
+++ b/packages/commerce-server/src/lib/commerce/commerce-route.ts
@@ -26,9 +26,7 @@ export const consoleCommerceLogger: CommerceLogger = {
 /** Returns the host's id for this request (for example one set by its load balancer), if any. */
 export type CommerceCorrelationIdResolver = (req: Request) => string | undefined;
 
-export const CORRELATION_ID_HEADER = 'X-Correlation-Id';
-
-// Ids are echoed into logs and a response header, so reject anything that could forge either.
+// Ids are echoed into logs and response bodies, so reject anything that could forge either.
 const CORRELATION_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 
 export function resolveCorrelationId(req: Request, resolver?: CommerceCorrelationIdResolver): string {
@@ -41,7 +39,6 @@ function correlationIdFor(req: Request, res: Response): string {
   if (typeof existing === 'string') return existing;
   const correlationId = resolveCorrelationId(req);
   res.locals.commerceCorrelationId = correlationId;
-  if (!res.headersSent) res.setHeader(CORRELATION_ID_HEADER, correlationId);
   return correlationId;
 }
 
diff --git a/packages/commerce-server/src/router.test.ts b/packages/commerce-server/src/router.test.ts
index 27be41bb..6e2751bf 100644
--- a/packages/commerce-server/src/router.test.ts
+++ b/packages/commerce-server/src/router.test.ts
@@ -575,7 +575,7 @@ describe('Commerce router mounting', (): void => {
     );
     const body = (await result.json()) as { correlationId: string };
     expect(result.status).toBe(503);
-    expect(result.headers.get('x-correlation-id')).toBe(body.correlationId);
+    expect(result.headers.has('x-correlation-id')).toBe(false);
     expect(JSON.stringify(body)).not.toContain('secret config detail');
     expect(logger.error).toHaveBeenCalledWith(
       'commerce-server: Failed to load products',
@@ -587,12 +587,15 @@ describe('Commerce router mounting', (): void => {
     ['a valid host id', 'edge-123', 'edge-123'],
     ['an id with unsafe characters', 'id with spaces; level=error', undefined],
   ])('uses %s from getCorrelationId when it is safe', async (_case, supplied, expected): Promise<void> => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
     const result = await requestThroughRouter(
-      createCommerceCatalogRouter(configuration, { getCorrelationId: (req) => req.get('x-request-id') }),
+      createCommerceCatalogRouter(failingConfiguration, {
+        getCorrelationId: (req) => req.get('x-request-id'),
+      }),
       '/config',
       { 'x-request-id': supplied },
     );
-    const correlationId = result.headers.get('x-correlation-id');
+    const { correlationId } = (await result.json()) as { correlationId: string };
     if (expected) expect(correlationId).toBe(expected);
     else expect(correlationId).toMatch(/^[0-9a-f-]{36}$/);
   });
diff --git a/packages/commerce-server/src/router.ts b/packages/commerce-server/src/router.ts
index fb91d0bf..7b1c5a41 100644
--- a/packages/commerce-server/src/router.ts
+++ b/packages/commerce-server/src/router.ts
@@ -4,7 +4,6 @@ import {
   createCheckoutReturnUrlValidator,
 } from './lib/commerce/checkout-return-urls';
 import {
-  CORRELATION_ID_HEADER,
   type CommerceCorrelationIdResolver,
   type CommerceLogger,
   consoleCommerceLogger,
@@ -63,7 +62,6 @@ export function createCommerceRouter(options: CreateCommerceRouterOptions = {}):
     const correlationId: string = resolveCorrelationId(req, options.getCorrelationId);
     res.locals.commerceCorrelationId = correlationId;
     res.locals.commerceLogger = logger;
-    res.setHeader(CORRELATION_ID_HEADER, correlationId);
     res.locals.commerceConfiguration = configuration;
     res.locals.commerceCheckoutReturnUrlValidator = validateCheckoutReturnUrls;
     next();

From 6ebcc94eaf8d0936b8c707187ca845d259575f3e Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 15:36:54 -0700
Subject: [PATCH 06/12] refactor(commerce-server): rename correlation id to
 request id

The id identifies one HTTP request, so name it requestId. Renames the body
field, the getRequestId router option, CommerceRequestIdResolver, and the log
context field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/quiet-route-failures.md            |  4 +--
 packages/commerce-server/README.md            |  6 ++--
 .../src/configuration-integration.test.ts     | 10 +++----
 .../src/get-order-status.test.ts              |  4 +--
 packages/commerce-server/src/index.ts         |  2 +-
 .../src/lib/commerce/commerce-route.ts        | 30 +++++++++----------
 packages/commerce-server/src/router.test.ts   | 27 ++++++++---------
 packages/commerce-server/src/router.ts        | 12 ++++----
 .../server/api/commerce/order-status/GET.ts   |  2 +-
 9 files changed, 47 insertions(+), 50 deletions(-)

diff --git a/.changeset/quiet-route-failures.md b/.changeset/quiet-route-failures.md
index f858697a..8ba4f2e3 100644
--- a/.changeset/quiet-route-failures.md
+++ b/.changeset/quiet-route-failures.md
@@ -2,7 +2,7 @@
 '@godaddy/gd-commerce-server': minor
 ---
 
-Standardize route error handling. Every failure now responds with `{ error, code, correlationId }` and no longer includes internal error text in a `message` field.
+Standardize route error handling. Every failure now responds with `{ error, code, requestId }` and no longer includes internal error text in a `message` field.
 
 Status codes now reflect the cause:
 
@@ -11,6 +11,6 @@ Status codes now reflect the cause:
 - 404 for cart writes against a missing, expired, or completed cart; previously 500.
 - 500 only for unexpected errors.
 
-Hosts can pass `logger` and `getCorrelationId` to the router factories to receive failure detail and reuse their own request ids. In-process helpers throw exported `CommerceError` subclasses. `validateCommerceCartScope` was internal and is replaced by a throwing `assertCommerceCartScope`.
+Hosts can pass `logger` and `getRequestId` to the router factories to receive failure detail and reuse their own request ids. In-process helpers throw exported `CommerceError` subclasses. `validateCommerceCartScope` was internal and is replaced by a throwing `assertCommerceCartScope`.
 
 Hosts that read `message` or check for status 500 should switch to `code` and server-side logs.
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index 19257b7d..0fd96032 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -60,7 +60,7 @@ A return from hosted checkout is not proof of payment. The order-status route us
 
 ## Errors
 
-Every route reports failures the same way. The body is `{ "error": "<customer-facing message>", "code": "<code>", "correlationId": "<id>" }` (order-status also includes `success: false`). The same id is passed to the logger. Bodies never contain upstream messages, configuration details, or credentials.
+Every route reports failures the same way. The body is `{ "error": "<customer-facing message>", "code": "<code>", "requestId": "<id>" }` (order-status also includes `success: false`). The same id is passed to the logger. Bodies never contain upstream messages, configuration details, or credentials.
 
 | Status | `code` | Meaning |
 | --- | --- | --- |
@@ -79,8 +79,8 @@ createCommerceRouter({
   configuration,
   logger: { error: (message, context) => log.error(context, message) },
   // Use the host's request id when its edge sets one; unsafe or missing ids fall back to a UUID.
-  getCorrelationId: (req) => req.get('x-request-id'),
+  getRequestId: (req) => req.get('x-request-id'),
 });
 ```
 
-`createCommerceCatalogRouter` and `createGoDaddyPaymentsRouter` accept the same `{ logger, getCorrelationId }` as their last argument. The logger defaults to `console.error`. In-process helpers throw the exported `CommerceError` subclasses (`InvalidRequestError`, `NotFoundError`, `CommerceNotConfiguredError`, `UpstreamError`).
+`createCommerceCatalogRouter` and `createGoDaddyPaymentsRouter` accept the same `{ logger, getRequestId }` as their last argument. The logger defaults to `console.error`. In-process helpers throw the exported `CommerceError` subclasses (`InvalidRequestError`, `NotFoundError`, `CommerceNotConfiguredError`, `UpstreamError`).
diff --git a/packages/commerce-server/src/configuration-integration.test.ts b/packages/commerce-server/src/configuration-integration.test.ts
index 0ba445ca..c6755b2f 100644
--- a/packages/commerce-server/src/configuration-integration.test.ts
+++ b/packages/commerce-server/src/configuration-integration.test.ts
@@ -99,7 +99,7 @@ it('serves variant product details without querying SKUGroup.status', async ():
     expect(await archived.json()).toEqual({
       error: 'Product not found',
       code: 'not_found',
-      correlationId: expect.any(String),
+      requestId: expect.any(String),
     });
     expect(upstream).toHaveBeenCalledTimes(3);
   } finally {
@@ -280,14 +280,14 @@ it.each([
       if (!address || typeof address === 'string') throw new Error('Expected a listening TCP server');
       const response = await clientFetch(`http://127.0.0.1:${address.port}/api/commerce/cart/completed-cart`);
       expect(response.status).toBe(status);
-      const json = (await response.json()) as { correlationId?: string };
-      const correlationId = json.correlationId;
-      expect(json).toEqual(status === 200 ? body : { ...body, correlationId: expect.any(String) });
+      const json = (await response.json()) as { requestId?: string };
+      const requestId = json.requestId;
+      expect(json).toEqual(status === 200 ? body : { ...body, requestId: expect.any(String) });
       if (status === 502) {
         expect(consoleError).toHaveBeenCalledWith(
           'commerce-server: Failed to load cart',
           expect.objectContaining({
-            correlationId,
+            requestId,
             error: expect.objectContaining({ message: expect.stringContaining(message) }),
           }),
         );
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index 2a37870f..ff17d369 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -203,8 +203,8 @@ describe('order-status route', () => {
         `http://127.0.0.1:${address.port}/api/commerce/order-status${query}`,
       );
       const body = (await response.json()) as Record<string, unknown>;
-      expect(body.correlationId).toEqual(expect.any(String));
-      const { correlationId: _correlationId, ...stable } = body;
+      expect(body.requestId).toEqual(expect.any(String));
+      const { requestId: _requestId, ...stable } = body;
       return { status: response.status, body: stable };
     } finally {
       await new Promise<void>((resolve, reject) =>
diff --git a/packages/commerce-server/src/index.ts b/packages/commerce-server/src/index.ts
index ba0aec5c..3681e108 100644
--- a/packages/commerce-server/src/index.ts
+++ b/packages/commerce-server/src/index.ts
@@ -5,9 +5,9 @@ export {
 } from './lib/commerce/checkout-config';
 export type { CheckoutReturnUrls } from './lib/commerce/checkout-return-urls';
 export type {
-  CommerceCorrelationIdResolver,
   CommerceErrorLogContext,
   CommerceLogger,
+  CommerceRequestIdResolver,
 } from './lib/commerce/commerce-route';
 export {
   type CommerceConfig,
diff --git a/packages/commerce-server/src/lib/commerce/commerce-route.ts b/packages/commerce-server/src/lib/commerce/commerce-route.ts
index 591443ce..56026139 100644
--- a/packages/commerce-server/src/lib/commerce/commerce-route.ts
+++ b/packages/commerce-server/src/lib/commerce/commerce-route.ts
@@ -5,7 +5,7 @@ import { CommerceError, type CommerceErrorCode, UpstreamError } from './errors';
 import { classifyUpstreamError } from './upstream-errors';
 
 export interface CommerceErrorLogContext {
-  correlationId: string;
+  requestId: string;
   method: string;
   path: string;
   httpStatus: number;
@@ -24,22 +24,22 @@ export const consoleCommerceLogger: CommerceLogger = {
 };
 
 /** Returns the host's id for this request (for example one set by its load balancer), if any. */
-export type CommerceCorrelationIdResolver = (req: Request) => string | undefined;
+export type CommerceRequestIdResolver = (req: Request) => string | undefined;
 
 // Ids are echoed into logs and response bodies, so reject anything that could forge either.
-const CORRELATION_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 
-export function resolveCorrelationId(req: Request, resolver?: CommerceCorrelationIdResolver): string {
+export function resolveRequestId(req: Request, resolver?: CommerceRequestIdResolver): string {
   const supplied = resolver?.(req);
-  return supplied && CORRELATION_ID_PATTERN.test(supplied) ? supplied : randomUUID();
+  return supplied && REQUEST_ID_PATTERN.test(supplied) ? supplied : randomUUID();
 }
 
-function correlationIdFor(req: Request, res: Response): string {
-  const existing: unknown = res.locals.commerceCorrelationId;
+function requestIdFor(req: Request, res: Response): string {
+  const existing: unknown = res.locals.commerceRequestId;
   if (typeof existing === 'string') return existing;
-  const correlationId = resolveCorrelationId(req);
-  res.locals.commerceCorrelationId = correlationId;
-  return correlationId;
+  const requestId = resolveRequestId(req);
+  res.locals.commerceRequestId = requestId;
+  return requestId;
 }
 
 function loggerFor(res: Response): CommerceLogger {
@@ -69,11 +69,11 @@ export function sendCommerceError(
         : undefined;
   const httpStatus = resolved?.httpStatus ?? 500;
   const code: CommerceErrorCode = resolved?.code ?? 'internal_error';
-  const correlationId = correlationIdFor(req, res);
+  const requestId = requestIdFor(req, res);
 
   if (httpStatus >= 500) {
     loggerFor(res).error(`commerce-server: ${label}`, {
-      correlationId,
+      requestId,
       method: req.method,
       path: req.path,
       httpStatus,
@@ -84,13 +84,11 @@ export function sendCommerceError(
   }
 
   if (res.headersSent) return;
-  res
-    .status(httpStatus)
-    .json({ ...failureFields, error: resolved?.publicMessage ?? label, code, correlationId });
+  res.status(httpStatus).json({ ...failureFields, error: resolved?.publicMessage ?? label, code, requestId });
 }
 
 export interface CommerceRouteOptions {
-  /** Fields every failure body carries in addition to `error`, `code`, and `correlationId`. */
+  /** Fields every failure body carries in addition to `error`, `code`, and `requestId`. */
   failureFields?: Record<string, unknown>;
 }
 
diff --git a/packages/commerce-server/src/router.test.ts b/packages/commerce-server/src/router.test.ts
index 6e2751bf..242f9bd8 100644
--- a/packages/commerce-server/src/router.test.ts
+++ b/packages/commerce-server/src/router.test.ts
@@ -183,7 +183,7 @@ describe('Commerce scoped routes', () => {
     expect(res.json).toHaveBeenCalledWith({
       error: 'Commerce configuration is unavailable. Complete the store connection before continuing.',
       code: 'not_configured',
-      correlationId: expect.any(String),
+      requestId: expect.any(String),
     });
     const [, context] = consoleError.mock.calls[0] ?? [];
     expect((context as { error: Error }).error.cause).toEqual(new Error('Missing channel'));
@@ -304,7 +304,7 @@ describe('Commerce scoped routes', () => {
     expect(res.json).toHaveBeenCalledWith({
       error: 'Failed to load cart',
       code: expect.stringMatching(/^upstream_(?:error|unauthorized)$/),
-      correlationId: expect.any(String),
+      requestId: expect.any(String),
     });
     expect(consoleError).toHaveBeenCalledWith(
       'commerce-server: Failed to load cart',
@@ -404,7 +404,7 @@ describe('Commerce scoped routes', () => {
       expect(res.json).toHaveBeenCalledWith({
         error: label,
         code: 'internal_error',
-        correlationId: expect.any(String),
+        requestId: expect.any(String),
       });
       expect(consoleError).toHaveBeenCalledWith(
         `commerce-server: ${label}`,
@@ -451,7 +451,7 @@ describe('Commerce scoped routes', () => {
       expect(res.json).toHaveBeenCalledWith({
         error: label,
         code: 'upstream_error',
-        correlationId: expect.any(String),
+        requestId: expect.any(String),
       });
       expect(JSON.stringify(vi.mocked(res.json).mock.calls)).not.toContain('secret-upstream-detail');
       expect(consoleError).toHaveBeenCalledWith(
@@ -481,7 +481,7 @@ describe('Commerce scoped routes', () => {
       expect(res.json).toHaveBeenCalledWith({
         error: 'Cart not found',
         code: 'not_found',
-        correlationId: expect.any(String),
+        requestId: expect.any(String),
       });
     },
   );
@@ -567,36 +567,35 @@ describe('Commerce router mounting', (): void => {
     },
   };
 
-  it('logs failures through the host logger with the response correlation id', async (): Promise<void> => {
+  it('logs failures through the host logger with the response request id', async (): Promise<void> => {
     const logger = { error: vi.fn() };
     const result = await requestThroughRouter(
       createCommerceCatalogRouter(failingConfiguration, { logger }),
       '/products',
     );
-    const body = (await result.json()) as { correlationId: string };
+    const body = (await result.json()) as { requestId: string };
     expect(result.status).toBe(503);
-    expect(result.headers.has('x-correlation-id')).toBe(false);
     expect(JSON.stringify(body)).not.toContain('secret config detail');
     expect(logger.error).toHaveBeenCalledWith(
       'commerce-server: Failed to load products',
-      expect.objectContaining({ correlationId: body.correlationId, httpStatus: 503, code: 'not_configured' }),
+      expect.objectContaining({ requestId: body.requestId, httpStatus: 503, code: 'not_configured' }),
     );
   });
 
   it.each([
     ['a valid host id', 'edge-123', 'edge-123'],
     ['an id with unsafe characters', 'id with spaces; level=error', undefined],
-  ])('uses %s from getCorrelationId when it is safe', async (_case, supplied, expected): Promise<void> => {
+  ])('uses %s from getRequestId when it is safe', async (_case, supplied, expected): Promise<void> => {
     vi.spyOn(console, 'error').mockImplementation(() => {});
     const result = await requestThroughRouter(
       createCommerceCatalogRouter(failingConfiguration, {
-        getCorrelationId: (req) => req.get('x-request-id'),
+        getRequestId: (req) => req.get('x-request-id'),
       }),
       '/config',
       { 'x-request-id': supplied },
     );
-    const { correlationId } = (await result.json()) as { correlationId: string };
-    if (expected) expect(correlationId).toBe(expected);
-    else expect(correlationId).toMatch(/^[0-9a-f-]{36}$/);
+    const { requestId } = (await result.json()) as { requestId: string };
+    if (expected) expect(requestId).toBe(expected);
+    else expect(requestId).toMatch(/^[0-9a-f-]{36}$/);
   });
 });
diff --git a/packages/commerce-server/src/router.ts b/packages/commerce-server/src/router.ts
index 7b1c5a41..8e7a54e8 100644
--- a/packages/commerce-server/src/router.ts
+++ b/packages/commerce-server/src/router.ts
@@ -4,10 +4,10 @@ import {
   createCheckoutReturnUrlValidator,
 } from './lib/commerce/checkout-return-urls';
 import {
-  type CommerceCorrelationIdResolver,
   type CommerceLogger,
+  type CommerceRequestIdResolver,
   consoleCommerceLogger,
-  resolveCorrelationId,
+  resolveRequestId,
 } from './lib/commerce/commerce-route';
 import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './lib/commerce/config';
 import cartDiscountPost from './server/api/commerce/cart/[id]/discounts/POST';
@@ -28,7 +28,7 @@ export interface CommerceRouterFeatures {
   payments?: boolean;
 }
 
-/** Where failure detail is logged and how each request's correlation id is chosen. */
+/** Where failure detail is logged and how each request's id is chosen. */
 export interface CommerceRouterObservabilityOptions {
   /** Receives 5xx failure detail. Defaults to `console.error`. */
   logger?: CommerceLogger;
@@ -36,7 +36,7 @@ export interface CommerceRouterObservabilityOptions {
    * Returns the host's id for the request, for example `(req) => req.get('x-request-id')` when
    * the host's edge sets that header. Invalid or missing ids fall back to a random UUID.
    */
-  getCorrelationId?: CommerceCorrelationIdResolver;
+  getRequestId?: CommerceRequestIdResolver;
 }
 
 export interface CreateCommerceRouterOptions extends CommerceRouterObservabilityOptions {
@@ -59,8 +59,8 @@ export function createCommerceRouter(options: CreateCommerceRouterOptions = {}):
     : undefined;
 
   router.use((req, res, next): void => {
-    const correlationId: string = resolveCorrelationId(req, options.getCorrelationId);
-    res.locals.commerceCorrelationId = correlationId;
+    const requestId: string = resolveRequestId(req, options.getRequestId);
+    res.locals.commerceRequestId = requestId;
     res.locals.commerceLogger = logger;
     res.locals.commerceConfiguration = configuration;
     res.locals.commerceCheckoutReturnUrlValidator = validateCheckoutReturnUrls;
diff --git a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
index fb1fe494..8a6f19f1 100644
--- a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
@@ -19,7 +19,7 @@
  *   502 Commerce or token failure (`code: upstream_error | upstream_unauthorized`)
  *   503 Commerce is not configured
  *   500 unexpected server failure
- * Failure bodies are { success: false, error, code, correlationId }.
+ * Failure bodies are { success: false, error, code, requestId }.
  * The host must authorize the caller's access to the requested order.
  */
 import type { Request, Response } from 'express';

From 30ca479f23d17123712db8f5bc1c15feb5a3e312 Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 16:07:56 -0700
Subject: [PATCH 07/12] docs(commerce-server): correct checkout
 binding-mismatch status in docblock

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../commerce-server/src/server/api/commerce/checkout/POST.ts   | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/commerce-server/src/server/api/commerce/checkout/POST.ts b/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
index c6a4c6ae..4ea8448e 100644
--- a/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/checkout/POST.ts
@@ -32,7 +32,8 @@
  *
  * Response: { url, id, draftOrderId, storeId, channelId, businessId,
  * storeName, sourceApp } from the created checkout session. The route returns
- * 500 if checkout-api does not preserve the configured store/channel binding.
+ * 502 (`upstream_error`) if checkout-api does not preserve the configured
+ * store/channel binding or the requested checkout settings.
  * Browser callers should redirect to `response.url`; this route does not
  * return a `redirectUrl` field.
  */

From eb364096aa52fed7f2e2b103481c08e2ee48eeb9 Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 17:10:43 -0700
Subject: [PATCH 08/12] fix(commerce-server): classify embedded GraphQL 401/403
 and guard the host logger

- GraphQLErrorWithCodes now reports upstream_unauthorized when any error
  carries a 401/403 status (extensions.status / extensions.http.status),
  not only when the HTTP response status is 401/403.
- sendCommerceError catches a throwing host logger, falls back to
  console.error with both errors, and still sends the standard body.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/configuration-integration.test.ts     | 49 +++++++++++++++++++
 .../src/lib/commerce/commerce-route.ts        | 10 +++-
 .../commerce-server/src/lib/commerce/gql.ts   |  5 +-
 packages/commerce-server/src/router.test.ts   | 41 ++++++++++++++++
 4 files changed, 102 insertions(+), 3 deletions(-)

diff --git a/packages/commerce-server/src/configuration-integration.test.ts b/packages/commerce-server/src/configuration-integration.test.ts
index c6755b2f..335d893f 100644
--- a/packages/commerce-server/src/configuration-integration.test.ts
+++ b/packages/commerce-server/src/configuration-integration.test.ts
@@ -299,3 +299,52 @@ it.each([
     }
   },
 );
+
+it.each([
+  ['extensions.http.status', { code: 'UNAUTHENTICATED', http: { status: 401 } }],
+  ['extensions.status', { code: 'FORBIDDEN', status: 403 }],
+])(
+  'reports an auth failure in an HTTP 200 GraphQL body (%s) as upstream_unauthorized',
+  async (_case, extensions): Promise<void> => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async (): Promise<Response> =>
+          Response.json({ data: { orderById: null }, errors: [{ message: 'Unauthorized', extensions }] }),
+      ),
+    );
+    const app = express();
+    app.use(
+      '/api/commerce',
+      createCommerceRouter({
+        configuration: createRuntimeCommerceConfiguration({
+          environment: {
+            GODADDY_OAUTH_CLIENT_ID: 'client-1',
+            GODADDY_OAUTH_CLIENT_SECRET: 'secret-1',
+            GODADDY_STORE_ID: 'store-1',
+            GODADDY_CHANNEL_ID: 'channel-1',
+            GODADDY_CURRENCY_CODE: 'USD',
+          },
+        }),
+      }),
+    );
+    const server = app.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    try {
+      const address = server.address();
+      if (!address || typeof address === 'string') throw new Error('Expected a listening TCP server');
+      const response = await clientFetch(`http://127.0.0.1:${address.port}/api/commerce/cart/cart-1`);
+      expect(response.status).toBe(502);
+      expect(await response.json()).toEqual({
+        error: 'Failed to load cart',
+        code: 'upstream_unauthorized',
+        requestId: expect.any(String),
+      });
+    } finally {
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+    }
+  },
+);
diff --git a/packages/commerce-server/src/lib/commerce/commerce-route.ts b/packages/commerce-server/src/lib/commerce/commerce-route.ts
index 56026139..f3265b00 100644
--- a/packages/commerce-server/src/lib/commerce/commerce-route.ts
+++ b/packages/commerce-server/src/lib/commerce/commerce-route.ts
@@ -72,7 +72,7 @@ export function sendCommerceError(
   const requestId = requestIdFor(req, res);
 
   if (httpStatus >= 500) {
-    loggerFor(res).error(`commerce-server: ${label}`, {
+    const context: CommerceErrorLogContext = {
       requestId,
       method: req.method,
       path: req.path,
@@ -80,7 +80,13 @@ export function sendCommerceError(
       code,
       ...(resolved?.details ? { details: resolved.details } : {}),
       error,
-    });
+    };
+    // A failing host logger must not prevent the failure response.
+    try {
+      loggerFor(res).error(`commerce-server: ${label}`, context);
+    } catch (loggerError) {
+      console.error(`commerce-server: ${label} (host logger failed)`, { ...context, loggerError });
+    }
   }
 
   if (res.headersSent) return;
diff --git a/packages/commerce-server/src/lib/commerce/gql.ts b/packages/commerce-server/src/lib/commerce/gql.ts
index d77e9b80..ac5dc578 100644
--- a/packages/commerce-server/src/lib/commerce/gql.ts
+++ b/packages/commerce-server/src/lib/commerce/gql.ts
@@ -54,8 +54,11 @@ export class GraphQLErrorWithCodes<
             .filter(Boolean)
             .join('; ');
 
+    // Commerce can report auth failures inside an HTTP 200 body via `extensions.(http.)status`.
     super(errorMessage, {
-      unauthorized: status === 401 || status === 403,
+      unauthorized: [status, ...errors.map((error) => error.status)].some(
+        (value) => value === 401 || value === 403,
+      ),
       details: {
         upstreamStatus: status,
         upstreamCodes: errors.map((error) => error.code).filter(Boolean),
diff --git a/packages/commerce-server/src/router.test.ts b/packages/commerce-server/src/router.test.ts
index 242f9bd8..d9a9d1bf 100644
--- a/packages/commerce-server/src/router.test.ts
+++ b/packages/commerce-server/src/router.test.ts
@@ -486,6 +486,23 @@ describe('Commerce scoped routes', () => {
     },
   );
 
+  it('reports a mixed not-found and embedded 403 as upstream_unauthorized without clearing the cart', async (): Promise<void> => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(gqlRequest).mockRejectedValueOnce(
+      new GraphQLErrorWithCodes([
+        { code: 'ORDER_NOT_FOUND', message: 'Order not found' },
+        { code: 'FORBIDDEN', message: 'Access denied', status: 403 },
+      ]),
+    );
+    const res = response();
+    await readCart(
+      { headers: {}, params: { id: 'cart-1' } } as unknown as Request,
+      res as unknown as Response,
+    );
+    expect(res.status).toHaveBeenCalledWith(502);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ code: 'upstream_unauthorized' }));
+  });
+
   it('reports an upstream 401 as upstream_unauthorized, not a caller authentication failure', async (): Promise<void> => {
     vi.spyOn(console, 'error').mockImplementation(() => {});
     vi.mocked(gqlRequest).mockRejectedValueOnce(
@@ -582,6 +599,30 @@ describe('Commerce router mounting', (): void => {
     );
   });
 
+  it('still sends the standard failure body when the host logger throws', async (): Promise<void> => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const loggerError = new Error('logger down');
+    const logger = {
+      error: (): never => {
+        throw loggerError;
+      },
+    };
+    const result = await requestThroughRouter(
+      createCommerceCatalogRouter(failingConfiguration, { logger }),
+      '/products',
+    );
+    expect(result.status).toBe(503);
+    await expect(result.json()).resolves.toEqual({
+      error: 'Commerce configuration is unavailable. Complete the store connection before continuing.',
+      code: 'not_configured',
+      requestId: expect.any(String),
+    });
+    expect(consoleError).toHaveBeenCalledWith(
+      'commerce-server: Failed to load products (host logger failed)',
+      expect.objectContaining({ httpStatus: 503, loggerError }),
+    );
+  });
+
   it.each([
     ['a valid host id', 'edge-123', 'edge-123'],
     ['an id with unsafe characters', 'id with spaces; level=error', undefined],

From b238a33fe75f161787bd4f13056875f6a4c2ca0c Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Mon, 5 Oct 2026 17:59:16 -0700
Subject: [PATCH 09/12] fix(commerce-server): treat incomplete order bindings
 as upstream failures

An Orders API response whose context lacks storeId or channelId fell
through to the store/channel mismatch check and was reported as 404.
Require both binding fields before comparing them so malformed responses
keep the generic 500 and server-side logging.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/get-order-status.test.ts              | 33 ++++++++++++-------
 .../src/lib/commerce/get-order-status.ts      | 12 +++++--
 2 files changed, 32 insertions(+), 13 deletions(-)

diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index 3b94ffd2..d348791a 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -126,17 +126,21 @@ describe('authorized order lookup', () => {
     },
   );
 
-  it.each([undefined, { ...order, context: undefined }])(
-    'rejects an incomplete order response',
-    async (result): Promise<void> => {
-      upstream
-        .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
-        .mockResolvedValueOnce(Response.json({ order: result }));
-      const lookup = getOrderStatus(order.id, configuration);
-      await expect(lookup).rejects.toThrow('Order lookup did not return the requested order');
-      await expect(lookup).rejects.not.toBeInstanceOf(OrderNotFoundError);
-    },
-  );
+  it.each([
+    undefined,
+    { ...order, context: undefined },
+    { ...order, context: {} },
+    { ...order, context: { channelId: order.context.channelId } },
+    { ...order, context: { storeId: order.context.storeId } },
+    { ...order, context: { ...order.context, storeId: '' } },
+  ])('rejects an incomplete order response', async (result): Promise<void> => {
+    upstream
+      .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+      .mockResolvedValueOnce(Response.json({ order: result }));
+    const lookup = getOrderStatus(order.id, configuration);
+    await expect(lookup).rejects.toThrow('Order lookup did not return the requested order');
+    await expect(lookup).rejects.not.toBeInstanceOf(OrderNotFoundError);
+  });
 
   it.each([
     { ...order, id: 'another-order' },
@@ -255,6 +259,13 @@ describe('order-status route', () => {
       ],
     ],
     ['an incomplete order', [Response.json({ access_token: 'order-token' }), Response.json({})]],
+    [
+      'an order missing its store binding',
+      [
+        Response.json({ access_token: 'order-token' }),
+        Response.json({ order: { ...order, context: { channelId: order.context.channelId } } }),
+      ],
+    ],
   ])(
     'returns a generic 500 for %s and logs the detail server-side',
     async (_case, responses): Promise<void> => {
diff --git a/packages/commerce-server/src/lib/commerce/get-order-status.ts b/packages/commerce-server/src/lib/commerce/get-order-status.ts
index d460e462..9b97b7e4 100644
--- a/packages/commerce-server/src/lib/commerce/get-order-status.ts
+++ b/packages/commerce-server/src/lib/commerce/get-order-status.ts
@@ -52,6 +52,10 @@ interface OrderResponse {
   };
 }
 
+function isBindingId(value: unknown): value is string {
+  return typeof value === 'string' && value !== '';
+}
+
 export async function getOrderStatus(
   orderId: string,
   configuration: CommerceConfiguration = createRuntimeCommerceConfiguration(),
@@ -90,9 +94,13 @@ export async function getOrderStatus(
 
   const data = (await response.json()) as OrderResponse;
   const order = data?.order;
-  if (!order?.id || !order.context) throw new Error('Order lookup did not return the requested order');
+  const context = order?.context;
+  // A binding missing either field is a malformed upstream response, not proof of another store or channel.
+  if (!order?.id || !isBindingId(context?.storeId) || !isBindingId(context?.channelId)) {
+    throw new Error('Order lookup did not return the requested order');
+  }
   // Report an order bound to another store or channel as missing so the route doesn't reveal it exists.
-  if (order.id !== orderId || order.context.storeId !== storeId || order.context.channelId !== channelId) {
+  if (order.id !== orderId || context.storeId !== storeId || context.channelId !== channelId) {
     throw new OrderNotFoundError();
   }
   const total = order.totals?.total;

From 456728b5cc95993f56250fa5f5925cefc86f8842 Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Tue, 6 Oct 2026 11:57:53 -0700
Subject: [PATCH 10/12] fix(commerce-server): tighten order-status error
 classification

- Treat an upstream order ID mismatch or non-string ID as a malformed
  response (500 + log) instead of not found.
- Cancel unread error response bodies and log upstream 404s.
- Match route errors by name so they survive duplicate package copies.
- Leave string ID validation to getOrderStatus.
- Restore mocks in afterEach.
- Bump the changeset to minor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/clear-order-status-errors.md       |  4 +-
 packages/commerce-server/README.md            |  2 +-
 .../src/get-order-status.test.ts              | 63 +++++++++++++++----
 .../src/lib/commerce/get-order-status.ts      | 22 +++++--
 .../server/api/commerce/order-status/GET.ts   | 14 +++--
 5 files changed, 81 insertions(+), 24 deletions(-)

diff --git a/.changeset/clear-order-status-errors.md b/.changeset/clear-order-status-errors.md
index 6ae979f0..42aabe02 100644
--- a/.changeset/clear-order-status-errors.md
+++ b/.changeset/clear-order-status-errors.md
@@ -1,5 +1,5 @@
 ---
-'@godaddy/gd-commerce-server': patch
+'@godaddy/gd-commerce-server': minor
 ---
 
-Return 400 from the order-status route for invalid order IDs and 404 when the order is missing or belongs to another store or channel, instead of 500. The 500 response no longer includes the internal error message; it is logged server-side instead. Export `InvalidOrderIdError`, `OrderNotFoundError`, and `ORDER_STATUS_UNKNOWN` for in-process `getOrderStatus()` callers.
+Return 400 from the order-status route for invalid order IDs and 404 when the order is missing or belongs to another store or channel, instead of 500. An upstream 404 is also logged with `console.warn`. The 500 response no longer includes the internal error message; it is logged server-side instead. Export `InvalidOrderIdError`, `OrderNotFoundError`, and `ORDER_STATUS_UNKNOWN` for in-process `getOrderStatus()` callers; check `error.name` rather than `instanceof` so the check holds when a host has more than one copy of this package.
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index 4a961c22..b53e433c 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -56,4 +56,4 @@ Configure `checkoutReturnUrls` on the router using trusted deployment settings.
 
 Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of `createCheckoutSession()` own their return URLs and must construct or validate them server-side.
 
-A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) and 404 when the Orders API has no such order or the order belongs to another store or channel. Credential and other upstream failures return 500 with a generic body; the detail is logged server-side with `console.error`. In-process callers can check for the exported `InvalidOrderIdError` and `OrderNotFoundError`. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) and 404 when the Orders API has no such order or the order belongs to another store or channel. Because the Orders API also returns 404 for a misconfigured store ID or API base URL, upstream 404s are logged with `console.warn`. Credential and other upstream failures, including a response for a different order ID, return 500 with a generic body; the detail is logged server-side with `console.error`. In-process callers can identify the exported `InvalidOrderIdError` and `OrderNotFoundError` by `error.name`; prefer that to `instanceof`, which fails when a host has more than one copy of this package. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index d348791a..4467f74d 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -52,6 +52,7 @@ beforeEach((): void => {
 });
 afterEach((): void => {
   vi.unstubAllGlobals();
+  vi.restoreAllMocks();
 });
 
 describe('authorized order lookup', () => {
@@ -133,7 +134,10 @@ describe('authorized order lookup', () => {
     { ...order, context: { channelId: order.context.channelId } },
     { ...order, context: { storeId: order.context.storeId } },
     { ...order, context: { ...order.context, storeId: '' } },
-  ])('rejects an incomplete order response', async (result): Promise<void> => {
+    { ...order, id: undefined },
+    { ...order, id: 42 },
+    { ...order, id: 'another-order' },
+  ])('rejects an incomplete or mismatched order response', async (result): Promise<void> => {
     upstream
       .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
       .mockResolvedValueOnce(Response.json({ order: result }));
@@ -143,37 +147,39 @@ describe('authorized order lookup', () => {
   });
 
   it.each([
-    { ...order, id: 'another-order' },
     { ...order, context: { ...order.context, storeId: 'another-store' } },
     { ...order, context: { ...order.context, channelId: 'another-channel' } },
-  ])(
-    'reports an order bound to another order, store, or channel as not found',
-    async (result): Promise<void> => {
-      upstream
-        .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
-        .mockResolvedValueOnce(Response.json({ order: result }));
-      await expect(getOrderStatus(order.id, configuration)).rejects.toBeInstanceOf(OrderNotFoundError);
-    },
-  );
+  ])('reports an order bound to another store or channel as not found', async (result): Promise<void> => {
+    upstream
+      .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+      .mockResolvedValueOnce(Response.json({ order: result }));
+    await expect(getOrderStatus(order.id, configuration)).rejects.toBeInstanceOf(OrderNotFoundError);
+  });
 
-  it('reports an upstream 404 as not found without exposing its body', async (): Promise<void> => {
+  it('reports an upstream 404 as not found, logs it, and releases the body', async (): Promise<void> => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation((): void => {});
+    const cancel = vi.spyOn(ReadableStream.prototype, 'cancel');
     upstream
       .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
       .mockResolvedValueOnce(new Response('Private upstream details', { status: 404 }));
     const lookup = getOrderStatus(order.id, configuration);
     await expect(lookup).rejects.toBeInstanceOf(OrderNotFoundError);
     await expect(lookup).rejects.toThrow(/^Order not found$/);
+    expect(warn).toHaveBeenCalledWith('getOrderStatus: Orders API returned 404 for store store-1');
+    expect(cancel).toHaveBeenCalledTimes(1);
   });
 
   it.each([401, 403, 500])(
     'preserves an upstream order lookup failure (%i) without exposing its body',
     async (status): Promise<void> => {
+      const cancel = vi.spyOn(ReadableStream.prototype, 'cancel');
       upstream
         .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
         .mockResolvedValueOnce(new Response('Private upstream details', { status }));
       await expect(getOrderStatus(order.id, configuration)).rejects.toThrow(
         `Failed to load order: upstream returned ${status}`,
       );
+      expect(cancel).toHaveBeenCalledTimes(1);
     },
   );
 
@@ -240,6 +246,7 @@ describe('order-status route', () => {
       Response.json({ order: { ...order, context: { ...order.context, storeId: 'another-store' } } }),
     ],
   ])('returns 404 for %s', async (_case, orderResponse): Promise<void> => {
+    vi.spyOn(console, 'warn').mockImplementation((): void => {});
     upstream
       .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
       .mockResolvedValueOnce(orderResponse);
@@ -266,6 +273,13 @@ describe('order-status route', () => {
         Response.json({ order: { ...order, context: { channelId: order.context.channelId } } }),
       ],
     ],
+    [
+      'a different order ID',
+      [
+        Response.json({ access_token: 'order-token' }),
+        Response.json({ order: { ...order, id: 'another-order' } }),
+      ],
+    ],
   ])(
     'returns a generic 500 for %s and logs the detail server-side',
     async (_case, responses): Promise<void> => {
@@ -274,7 +288,30 @@ describe('order-status route', () => {
       const result = await requestOrderStatus(`?orderId=${order.id}`);
       expect(result).toEqual({ status: 500, body: { success: false, error: 'Failed to get order status' } });
       expect(log).toHaveBeenCalledWith('order-status: failed to get order status', expect.any(Error));
-      log.mockRestore();
     },
   );
 });
+
+describe('order-status route with another copy of the package', () => {
+  afterEach((): void => {
+    vi.doUnmock('@/lib/commerce/get-order-status');
+    vi.resetModules();
+  });
+
+  it.each([
+    ['InvalidOrderIdError', 400, 'missing or invalid orderId query parameter'],
+    ['OrderNotFoundError', 404, 'Order not found'],
+  ])('matches a %s thrown by a different class by name', async (name, status, error): Promise<void> => {
+    vi.resetModules();
+    vi.doMock('@/lib/commerce/get-order-status', () => ({
+      getOrderStatus: async (): Promise<never> => {
+        throw Object.assign(new Error('from another copy'), { name });
+      },
+    }));
+    const { default: handler } = await import('./server/api/commerce/order-status/GET');
+    const res = { locals: {}, status: vi.fn().mockReturnThis(), json: vi.fn().mockReturnThis() };
+    await handler({ query: { orderId: order.id } } as never, res as never);
+    expect(res.status).toHaveBeenCalledWith(status);
+    expect(res.json).toHaveBeenCalledWith({ success: false, error });
+  });
+});
diff --git a/packages/commerce-server/src/lib/commerce/get-order-status.ts b/packages/commerce-server/src/lib/commerce/get-order-status.ts
index 9b97b7e4..85541815 100644
--- a/packages/commerce-server/src/lib/commerce/get-order-status.ts
+++ b/packages/commerce-server/src/lib/commerce/get-order-status.ts
@@ -89,18 +89,32 @@ export async function getOrderStatus(
       cache: 'no-store',
     },
   );
-  if (response.status === 404) throw new OrderNotFoundError();
-  if (!response.ok) throw new Error(`Failed to load order: upstream returned ${response.status}`);
+  if (!response.ok) {
+    // Unread bodies can hold pooled connections while callers poll.
+    await response.body?.cancel();
+    if (response.status === 404) {
+      // The Orders API doesn't distinguish a missing order from a wrong store or base URL, so log for diagnosis.
+      console.warn(`getOrderStatus: Orders API returned 404 for store ${storeId}`);
+      throw new OrderNotFoundError();
+    }
+    throw new Error(`Failed to load order: upstream returned ${response.status}`);
+  }
 
   const data = (await response.json()) as OrderResponse;
   const order = data?.order;
   const context = order?.context;
   // A binding missing either field is a malformed upstream response, not proof of another store or channel.
-  if (!order?.id || !isBindingId(context?.storeId) || !isBindingId(context?.channelId)) {
+  // So is a different order id: the lookup was by id, so it means upstream returned the wrong record.
+  if (
+    !isBindingId(order?.id) ||
+    order.id !== orderId ||
+    !isBindingId(context?.storeId) ||
+    !isBindingId(context?.channelId)
+  ) {
     throw new Error('Order lookup did not return the requested order');
   }
   // Report an order bound to another store or channel as missing so the route doesn't reveal it exists.
-  if (order.id !== orderId || context.storeId !== storeId || context.channelId !== channelId) {
+  if (context.storeId !== storeId || context.channelId !== channelId) {
     throw new OrderNotFoundError();
   }
   const total = order.totals?.total;
diff --git a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
index 6de46885..5791de86 100644
--- a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
@@ -22,14 +22,20 @@
 import type { Request, Response } from 'express';
 
 import { commerceConfigurationForResponse } from '@/lib/commerce/config';
-import { getOrderStatus, InvalidOrderIdError, OrderNotFoundError } from '@/lib/commerce/get-order-status';
+import { getOrderStatus } from '@/lib/commerce/get-order-status';
 
 const invalidOrderIdBody = { success: false, error: 'missing or invalid orderId query parameter' };
 
+// Matched by name, not instanceof, so errors still match when a host has several copies of this package.
+function hasErrorName(error: unknown, name: string): boolean {
+  return error instanceof Error && error.name === name;
+}
+
 export default async function handler(req: Request, res: Response): Promise<void> {
   try {
     const { orderId } = req.query;
-    if (!orderId || typeof orderId !== 'string') {
+    // getOrderStatus validates string IDs; only repeated or nested query values need rejecting here.
+    if (typeof orderId !== 'string') {
       res.status(400).json(invalidOrderIdBody);
       return;
     }
@@ -37,11 +43,11 @@ export default async function handler(req: Request, res: Response): Promise<void
     const order = await getOrderStatus(orderId, commerceConfigurationForResponse(res));
     res.status(200).json({ success: true, order });
   } catch (error) {
-    if (error instanceof InvalidOrderIdError) {
+    if (hasErrorName(error, 'InvalidOrderIdError')) {
       res.status(400).json(invalidOrderIdBody);
       return;
     }
-    if (error instanceof OrderNotFoundError) {
+    if (hasErrorName(error, 'OrderNotFoundError')) {
       res.status(404).json({ success: false, error: 'Order not found' });
       return;
     }

From c43083da500cfe66c07de065718a83f4410d1d6b Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Tue, 6 Oct 2026 12:20:04 -0700
Subject: [PATCH 11/12] fix(commerce-server): classify order-status 404s by the
 Orders API error code

The Orders API reports a missing order as 404 with code NOT_FOUND and an
undecodable order ID as 422 with code VALIDATION_FAILED. Only those map to
OrderNotFoundError and InvalidOrderIdError; any other 404, such as an
unrouted path or misconfigured base URL, is an upstream failure (logged 500).
This replaces the console.warn on every upstream 404.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/clear-order-status-errors.md       |  2 +-
 packages/commerce-server/README.md            |  2 +-
 .../src/get-order-status.test.ts              | 62 ++++++++++++++++---
 .../src/lib/commerce/get-order-status.ts      | 24 +++++--
 .../server/api/commerce/order-status/GET.ts   |  2 +-
 5 files changed, 75 insertions(+), 17 deletions(-)

diff --git a/.changeset/clear-order-status-errors.md b/.changeset/clear-order-status-errors.md
index 42aabe02..bcd7f745 100644
--- a/.changeset/clear-order-status-errors.md
+++ b/.changeset/clear-order-status-errors.md
@@ -2,4 +2,4 @@
 '@godaddy/gd-commerce-server': minor
 ---
 
-Return 400 from the order-status route for invalid order IDs and 404 when the order is missing or belongs to another store or channel, instead of 500. An upstream 404 is also logged with `console.warn`. The 500 response no longer includes the internal error message; it is logged server-side instead. Export `InvalidOrderIdError`, `OrderNotFoundError`, and `ORDER_STATUS_UNKNOWN` for in-process `getOrderStatus()` callers; check `error.name` rather than `instanceof` so the check holds when a host has more than one copy of this package.
+Return 400 from the order-status route for invalid order IDs, including IDs the Orders API rejects as malformed, and 404 when the Orders API reports the order missing or it belongs to another store or channel, instead of 500. A 404 without the Orders API's `NOT_FOUND` code, such as from a misconfigured base URL, stays a logged 500. The 500 response no longer includes the internal error message; it is logged server-side instead. Export `InvalidOrderIdError`, `OrderNotFoundError`, and `ORDER_STATUS_UNKNOWN` for in-process `getOrderStatus()` callers; check `error.name` rather than `instanceof` so the check holds when a host has more than one copy of this package.
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index b53e433c..91ed9574 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -56,4 +56,4 @@ Configure `checkoutReturnUrls` on the router using trusted deployment settings.
 
 Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of `createCheckoutSession()` own their return URLs and must construct or validate them server-side.
 
-A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) and 404 when the Orders API has no such order or the order belongs to another store or channel. Because the Orders API also returns 404 for a misconfigured store ID or API base URL, upstream 404s are logged with `console.warn`. Credential and other upstream failures, including a response for a different order ID, return 500 with a generic body; the detail is logged server-side with `console.error`. In-process callers can identify the exported `InvalidOrderIdError` and `OrderNotFoundError` by `error.name`; prefer that to `instanceof`, which fails when a host has more than one copy of this package. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) or one the Orders API rejects as malformed (422 `VALIDATION_FAILED`), and 404 when the Orders API reports the order missing (404 `NOT_FOUND`) or the order belongs to another store or channel. A 404 without that code, such as from a misconfigured API base URL, is treated as an upstream failure. Credential and other upstream failures, including a response for a different order ID, return 500 with a generic body; the detail is logged server-side with `console.error`. In-process callers can identify the exported `InvalidOrderIdError` and `OrderNotFoundError` by `error.name`; prefer that to `instanceof`, which fails when a host has more than one copy of this package. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index 4467f74d..0cb85279 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -34,6 +34,17 @@ const summary = {
   updatedAt: order.updatedAt,
   lineItems: [{ id: 'line-1', name: 'Mug', quantity: 1 }],
 };
+// Bodies the Orders API's REST error handler sends for a missing order and an undecodable ID.
+const ordersApiNotFound = (): Response =>
+  Response.json(
+    { code: 'NOT_FOUND', message: 'Order not found. Possible reasons: invalid orderId, storeID mismatch.' },
+    { status: 404 },
+  );
+const ordersApiInvalidId = (): Response =>
+  Response.json(
+    { code: 'VALIDATION_FAILED', message: 'Invalid global ID: completed-order' },
+    { status: 422 },
+  );
 let upstream: ReturnType<typeof vi.fn<typeof fetch>>;
 
 beforeEach((): void => {
@@ -156,17 +167,36 @@ describe('authorized order lookup', () => {
     await expect(getOrderStatus(order.id, configuration)).rejects.toBeInstanceOf(OrderNotFoundError);
   });
 
-  it('reports an upstream 404 as not found, logs it, and releases the body', async (): Promise<void> => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation((): void => {});
-    const cancel = vi.spyOn(ReadableStream.prototype, 'cancel');
+  it('reports an Orders API NOT_FOUND as not found without exposing its body', async (): Promise<void> => {
     upstream
       .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
-      .mockResolvedValueOnce(new Response('Private upstream details', { status: 404 }));
+      .mockResolvedValueOnce(ordersApiNotFound());
     const lookup = getOrderStatus(order.id, configuration);
     await expect(lookup).rejects.toBeInstanceOf(OrderNotFoundError);
     await expect(lookup).rejects.toThrow(/^Order not found$/);
-    expect(warn).toHaveBeenCalledWith('getOrderStatus: Orders API returned 404 for store store-1');
-    expect(cancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports an Orders API VALIDATION_FAILED for the order ID as an invalid order ID', async (): Promise<void> => {
+    upstream
+      .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+      .mockResolvedValueOnce(ordersApiInvalidId());
+    await expect(getOrderStatus(order.id, configuration)).rejects.toBeInstanceOf(InvalidOrderIdError);
+  });
+
+  it.each([
+    ['an HTML 404 from an unrouted path', new Response('<pre>Cannot GET /v1/x</pre>', { status: 404 })],
+    ['a JSON 404 without a code', Response.json({ message: 'Not Found' }, { status: 404 })],
+    ['a 404 with another code', Response.json({ code: 'ROUTE_NOT_FOUND' }, { status: 404 })],
+    ['a 422 with another code', Response.json({ code: 'CONFLICT' }, { status: 422 })],
+    ['a non-JSON 422', new Response('Unprocessable', { status: 422 })],
+  ])('treats %s as an upstream failure', async (_case, failure): Promise<void> => {
+    upstream
+      .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+      .mockResolvedValueOnce(failure);
+    const lookup = getOrderStatus(order.id, configuration);
+    await expect(lookup).rejects.toThrow(`Failed to load order: upstream returned ${failure.status}`);
+    await expect(lookup).rejects.not.toBeInstanceOf(OrderNotFoundError);
+    await expect(lookup).rejects.not.toBeInstanceOf(InvalidOrderIdError);
   });
 
   it.each([401, 403, 500])(
@@ -239,14 +269,23 @@ describe('order-status route', () => {
     },
   );
 
+  it('returns 400 when the Orders API rejects the order ID format', async (): Promise<void> => {
+    upstream
+      .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
+      .mockResolvedValueOnce(ordersApiInvalidId());
+    await expect(requestOrderStatus(`?orderId=${order.id}`)).resolves.toEqual({
+      status: 400,
+      body: { success: false, error: 'missing or invalid orderId query parameter' },
+    });
+  });
+
   it.each([
-    ['an upstream 404', new Response('Private upstream details', { status: 404 })],
+    ['an Orders API NOT_FOUND', ordersApiNotFound()],
     [
       'another store',
       Response.json({ order: { ...order, context: { ...order.context, storeId: 'another-store' } } }),
     ],
   ])('returns 404 for %s', async (_case, orderResponse): Promise<void> => {
-    vi.spyOn(console, 'warn').mockImplementation((): void => {});
     upstream
       .mockResolvedValueOnce(Response.json({ access_token: 'order-token' }))
       .mockResolvedValueOnce(orderResponse);
@@ -273,6 +312,13 @@ describe('order-status route', () => {
         Response.json({ order: { ...order, context: { channelId: order.context.channelId } } }),
       ],
     ],
+    [
+      'a 404 from an unrouted path',
+      [
+        Response.json({ access_token: 'order-token' }),
+        new Response('<pre>Cannot GET /v1/x</pre>', { status: 404 }),
+      ],
+    ],
     [
       'a different order ID',
       [
diff --git a/packages/commerce-server/src/lib/commerce/get-order-status.ts b/packages/commerce-server/src/lib/commerce/get-order-status.ts
index 85541815..48d5e4f5 100644
--- a/packages/commerce-server/src/lib/commerce/get-order-status.ts
+++ b/packages/commerce-server/src/lib/commerce/get-order-status.ts
@@ -56,6 +56,17 @@ function isBindingId(value: unknown): value is string {
   return typeof value === 'string' && value !== '';
 }
 
+async function readErrorCode(response: Response): Promise<string | null> {
+  try {
+    const body: unknown = await response.json();
+    return body && typeof body === 'object' && 'code' in body && typeof body.code === 'string'
+      ? body.code
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function getOrderStatus(
   orderId: string,
   configuration: CommerceConfiguration = createRuntimeCommerceConfiguration(),
@@ -90,13 +101,14 @@ export async function getOrderStatus(
     },
   );
   if (!response.ok) {
+    // The Orders API reports a missing order as 404 NOT_FOUND and an ID it can't decode as 422
+    // VALIDATION_FAILED. A 404 without that code comes from an unrouted path or base URL.
+    const code =
+      response.status === 404 || response.status === 422 ? await readErrorCode(response) : undefined;
     // Unread bodies can hold pooled connections while callers poll.
-    await response.body?.cancel();
-    if (response.status === 404) {
-      // The Orders API doesn't distinguish a missing order from a wrong store or base URL, so log for diagnosis.
-      console.warn(`getOrderStatus: Orders API returned 404 for store ${storeId}`);
-      throw new OrderNotFoundError();
-    }
+    if (code === undefined) await response.body?.cancel();
+    if (response.status === 404 && code === 'NOT_FOUND') throw new OrderNotFoundError();
+    if (response.status === 422 && code === 'VALIDATION_FAILED') throw new InvalidOrderIdError();
     throw new Error(`Failed to load order: upstream returned ${response.status}`);
   }
 
diff --git a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
index 5791de86..cf8e288e 100644
--- a/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/order-status/GET.ts
@@ -14,7 +14,7 @@
  * Responses:
  *   200 { success: true, order: CommerceOrderStatus }
  *       order.status is the payment status returned by the authorized Orders API.
- *   400 missing, blank, padded, `.` or `..` orderId
+ *   400 missing, blank, padded, `.` or `..` orderId, or one the Orders API rejects as malformed
  *   404 no order with that id in the configured store and channel
  *   500 credential, upstream, or configuration failure
  * The host must authorize the caller's access to the requested order.

From 34f0279324c89dfcb06b1c841bdfd755d9a41f2f Mon Sep 17 00:00:00 2001
From: Aaron Nam <112416280+anam-godaddy@users.noreply.github.com>
Date: Tue, 6 Oct 2026 12:39:28 -0700
Subject: [PATCH 12/12] fix(commerce-server): address route error handling
 review

- Scope the cart-not-found rule to /cart/:id routes via a per-route
  classifyUpstreamError option. Creating a cart and catalog routes no
  longer turn "Order not found" into 404 "Cart not found".
- Resolve the request id lazily, once, from the resolver stored in
  res.locals, and fall back to a UUID when the host's getRequestId throws.
  Type the router's res.locals instead of duck-typing the logger.
- Classify OAuth 400s by the RFC 6749 `error` field. Only invalid_client,
  invalid_grant, unauthorized_client, and invalid_scope are
  upstream_unauthorized; other 400s are upstream_error.
- Wrap configuration reads in getOrderStatus and createCheckoutSession so
  a throwing host configuration is CommerceNotConfiguredError in-process
  too.
- Log the order lookup endpoint and Orders API error code with its
  upstream failures, matching gqlRequest's details.
- Docs: checkout with a stale draftOrderId stays 502; in-process callers
  check error.code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/quiet-route-failures.md            |  6 +-
 packages/commerce-server/README.md            |  8 +--
 .../src/create-checkout-session.test.ts       | 10 ++--
 .../src/get-order-status.test.ts              | 29 ++++++++++
 .../src/lib/commerce/checkout-subgraph.ts     | 28 +++++++++-
 .../src/lib/commerce/commerce-route.ts        | 56 ++++++++++++-------
 .../src/lib/commerce/config.ts                | 27 +++++----
 .../lib/commerce/create-checkout-session.ts   | 11 +++-
 .../src/lib/commerce/get-order-status.ts      | 25 +++++++--
 .../src/lib/commerce/upstream-errors.ts       |  9 ++-
 packages/commerce-server/src/router.test.ts   | 42 ++++++++++++++
 packages/commerce-server/src/router.ts        | 12 ++--
 .../src/server/api/commerce/cart/[id]/GET.ts  |  6 +-
 .../api/commerce/cart/[id]/discounts/POST.ts  |  5 +-
 .../api/commerce/cart/[id]/items/POST.ts      |  5 +-
 .../cart/[id]/items/[itemId]/DELETE.ts        |  5 +-
 .../cart/[id]/items/[itemId]/PATCH.ts         |  5 +-
 17 files changed, 221 insertions(+), 68 deletions(-)

diff --git a/.changeset/quiet-route-failures.md b/.changeset/quiet-route-failures.md
index 8ba4f2e3..7af5840b 100644
--- a/.changeset/quiet-route-failures.md
+++ b/.changeset/quiet-route-failures.md
@@ -6,11 +6,11 @@ Standardize route error handling. Every failure now responds with `{ error, code
 
 Status codes now reflect the cause:
 
-- 502 for Commerce failures, including rejected OAuth credentials (`upstream_unauthorized`); previously 500.
+- 502 for Commerce failures, including rejected OAuth credentials (`upstream_unauthorized`); previously 500. This includes order-status upstream failures, which were 500. An OAuth 400 is `upstream_unauthorized` only for `invalid_client`, `invalid_grant`, `unauthorized_client`, or `invalid_scope`.
 - 503 for missing or unreadable configuration on every route; previously 500 everywhere except `/config`.
-- 404 for cart writes against a missing, expired, or completed cart; previously 500.
+- 404 for writes to an existing cart (`/cart/:id/...`) that is missing, expired, or completed; previously 500. Creating a cart and checkout are not classified this way and return 502.
 - 500 only for unexpected errors.
 
-Hosts can pass `logger` and `getRequestId` to the router factories to receive failure detail and reuse their own request ids. In-process helpers throw exported `CommerceError` subclasses. `validateCommerceCartScope` was internal and is replaced by a throwing `assertCommerceCartScope`.
+Hosts can pass `logger` and `getRequestId` to the router factories to receive failure detail and reuse their own request ids; a throwing `getRequestId` falls back to a generated id. In-process helpers, including `getOrderStatus()` and `createCheckoutSession()`, throw exported `CommerceError` subclasses, also when a host configuration throws while being read. Check `error.code` rather than `instanceof` or `error.name`; it holds when a host has more than one copy of this package. `validateCommerceCartScope` was internal and is replaced by a throwing `assertCommerceCartScope`.
 
 Hosts that read `message` or check for status 500 should switch to `code` and server-side logs.
diff --git a/packages/commerce-server/README.md b/packages/commerce-server/README.md
index 9aa01d57..68f737ce 100644
--- a/packages/commerce-server/README.md
+++ b/packages/commerce-server/README.md
@@ -56,7 +56,7 @@ Configure `checkoutReturnUrls` on the router using trusted deployment settings.
 
 Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of `createCheckoutSession()` own their return URLs and must construct or validate them server-side.
 
-A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) or one the Orders API rejects as malformed (422 `VALIDATION_FAILED`), and 404 when the Orders API reports the order missing (404 `NOT_FOUND`) or the order belongs to another store or channel. A 404 without that code, such as from a misconfigured API base URL, is an upstream failure. Token and other Commerce failures, including a response for a different order ID, return 502 and unreadable configuration returns 503 (see [Errors](#errors)). In-process callers can check for the exported `InvalidOrderIdError` and `OrderNotFoundError`. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) or one the Orders API rejects as malformed (422 `VALIDATION_FAILED`), and 404 when the Orders API reports the order missing (404 `NOT_FOUND`) or the order belongs to another store or channel. A 404 without that code, such as from a misconfigured API base URL, is an upstream failure. Token and other Commerce failures, including a response for a different order ID, return 502 and unreadable configuration returns 503 (see [Errors](#errors)). Hosts must authenticate callers and authorize access to each requested order before exposing this route.
 
 ## Errors
 
@@ -65,9 +65,9 @@ Every route reports failures the same way. The body is `{ "error": "<customer-fa
 | Status | `code` | Meaning |
 | --- | --- | --- |
 | 400 | `invalid_request` | Missing or invalid input. |
-| 404 | `not_found` | Missing order or product, or a cart write against a missing, expired, or completed cart. Cart reads keep returning `200 { "cart": null }`. |
+| 404 | `not_found` | Missing order or product, or a write to an existing cart (`/cart/:id/...`) that is missing, expired, or completed. Cart reads keep returning `200 { "cart": null }`. Checkout with a stale or completed `draftOrderId` is not yet distinguished and returns 502. |
 | 409 | `scope_mismatch` | `X-Commerce-Scope` no longer matches the configured store binding. |
-| 502 | `upstream_unauthorized` | Commerce rejected this server's OAuth client or requested scope. It concerns server credentials, not the caller, so it is never reported as 401/403. |
+| 502 | `upstream_unauthorized` | Commerce rejected this server's OAuth client or requested scope (HTTP 401/403, or an OAuth 400 with `invalid_client`, `invalid_grant`, `unauthorized_client`, or `invalid_scope`). It concerns server credentials, not the caller, so it is never reported as 401/403. |
 | 502 | `upstream_error` | Commerce failed, returned an unexpected response, or could not be reached. |
 | 503 | `not_configured` | Configuration is missing or unreadable, or checkout return URLs are not configured. |
 | 500 | `internal_error` | An unexpected error in this package. |
@@ -83,4 +83,4 @@ createCommerceRouter({
 });
 ```
 
-`createCommerceCatalogRouter` and `createGoDaddyPaymentsRouter` accept the same `{ logger, getRequestId }` as their last argument. The logger defaults to `console.error`. In-process helpers throw the exported `CommerceError` subclasses (`InvalidRequestError`, `NotFoundError`, `CommerceNotConfiguredError`, `UpstreamError`).
+`createCommerceCatalogRouter` and `createGoDaddyPaymentsRouter` accept the same `{ logger, getRequestId }` as their last argument. The logger defaults to `console.error`. In-process helpers throw the exported `CommerceError` subclasses (`InvalidRequestError`, `NotFoundError`, `CommerceNotConfiguredError`, `UpstreamError`), including when a host configuration throws while being read. Check `error.code` (for example `'not_found'`) rather than `instanceof`, which fails when a host has more than one copy of this package.
diff --git a/packages/commerce-server/src/create-checkout-session.test.ts b/packages/commerce-server/src/create-checkout-session.test.ts
index 1e615dd7..a5508c94 100644
--- a/packages/commerce-server/src/create-checkout-session.test.ts
+++ b/packages/commerce-server/src/create-checkout-session.test.ts
@@ -255,13 +255,13 @@ describe('createCheckoutSession', () => {
     ]);
   });
 
-  it('returns host configuration errors immediately without OAuth or checkout requests', async (): Promise<void> => {
+  it('reports host configuration errors as not configured without OAuth or checkout requests', async (): Promise<void> => {
+    const cause = new Error('Host configuration unavailable');
     vi.mocked(configuration.read).mockImplementation(() => {
-      throw new Error('Host configuration unavailable');
+      throw cause;
     });
-    await expect(createCheckoutSession(cart, configuration)).rejects.toThrow(
-      'Host configuration unavailable',
-    );
+    const error = await createCheckoutSession(cart, configuration).catch((thrown: unknown) => thrown);
+    expect(error).toMatchObject({ code: 'not_configured', httpStatus: 503, cause });
     expect(configuration.read).toHaveBeenCalledTimes(1);
     expect(mockGetOAuthAccessToken).not.toHaveBeenCalled();
     expect(mockGqlRequest).not.toHaveBeenCalled();
diff --git a/packages/commerce-server/src/get-order-status.test.ts b/packages/commerce-server/src/get-order-status.test.ts
index e9ea2921..9d8d96d8 100644
--- a/packages/commerce-server/src/get-order-status.test.ts
+++ b/packages/commerce-server/src/get-order-status.test.ts
@@ -219,6 +219,19 @@ describe('authorized order lookup', () => {
     expect(upstream).toHaveBeenCalledTimes(1);
   });
 
+  it('reports a host configuration that throws as not configured', async (): Promise<void> => {
+    const cause = new Error('secrets file missing');
+    const failing = {
+      read: (): never => {
+        throw cause;
+      },
+      readCheckout: configuration.readCheckout,
+    };
+    const error = await getOrderStatus(order.id, failing).catch((thrown: unknown) => thrown);
+    expect(error).toMatchObject({ code: 'not_configured', httpStatus: 503, cause });
+    expect(upstream).not.toHaveBeenCalled();
+  });
+
   it.each(['', ' ', '.', '..', ' completed-order', 'completed-order\n'])(
     'rejects invalid order ID %j before requesting credentials',
     async (id): Promise<void> => {
@@ -308,6 +321,22 @@ describe('order-status route', () => {
       'upstream_unauthorized',
       [new Response('Invalid scope', { status: 403 })],
     ],
+    [
+      'an OAuth invalid_scope rejection',
+      'upstream_unauthorized',
+      [Response.json({ error: 'invalid_scope' }, { status: 400 })],
+    ],
+    [
+      'an OAuth invalid_client rejection',
+      'upstream_unauthorized',
+      [Response.json({ error: 'invalid_client' }, { status: 400 })],
+    ],
+    [
+      'a malformed OAuth request',
+      'upstream_error',
+      [Response.json({ error: 'invalid_request' }, { status: 400 })],
+    ],
+    ['a non-JSON OAuth 400', 'upstream_error', [new Response('Bad Request', { status: 400 })]],
     [
       'an upstream 500',
       'upstream_error',
diff --git a/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts b/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts
index 0fdc4dc6..5d0b22a6 100644
--- a/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts
+++ b/packages/commerce-server/src/lib/commerce/checkout-subgraph.ts
@@ -336,6 +336,26 @@ export function authorizationHeaders({ accessToken }: AuthorizationHeadersInput)
   };
 }
 
+// RFC 6749 §5.2 errors that mean this server's client or its granted scope was rejected. Other 400s
+// (e.g. `invalid_request`, `unsupported_grant_type`) are a malformed request, not bad credentials.
+const UNAUTHORIZED_OAUTH_ERRORS: ReadonlySet<string> = new Set([
+  'invalid_client',
+  'invalid_grant',
+  'unauthorized_client',
+  'invalid_scope',
+]);
+
+async function readOAuthError(response: Response): Promise<string | undefined> {
+  try {
+    const body: unknown = await response.json();
+    return body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'
+      ? body.error
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function getOAuthAccessToken({
   clientId,
   clientSecret,
@@ -369,9 +389,13 @@ export async function getOAuthAccessToken({
   }
 
   if (!response.ok) {
+    const oauthError = response.status === 400 ? await readOAuthError(response) : undefined;
     throw new UpstreamError(`Failed to get access token: ${response.status} ${response.statusText}`, {
-      unauthorized: response.status === 400 || response.status === 401 || response.status === 403,
-      details: { upstreamStatus: response.status, scope },
+      unauthorized:
+        response.status === 401 ||
+        response.status === 403 ||
+        (oauthError !== undefined && UNAUTHORIZED_OAUTH_ERRORS.has(oauthError)),
+      details: { upstreamStatus: response.status, scope, oauthError },
     });
   }
 
diff --git a/packages/commerce-server/src/lib/commerce/commerce-route.ts b/packages/commerce-server/src/lib/commerce/commerce-route.ts
index f3265b00..d7983d54 100644
--- a/packages/commerce-server/src/lib/commerce/commerce-route.ts
+++ b/packages/commerce-server/src/lib/commerce/commerce-route.ts
@@ -2,7 +2,6 @@
 import { randomUUID } from 'node:crypto';
 import type { Request, Response } from 'express';
 import { CommerceError, type CommerceErrorCode, UpstreamError } from './errors';
-import { classifyUpstreamError } from './upstream-errors';
 
 export interface CommerceErrorLogContext {
   requestId: string;
@@ -29,24 +28,33 @@ export type CommerceRequestIdResolver = (req: Request) => string | undefined;
 // Ids are echoed into logs and response bodies, so reject anything that could forge either.
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 
-export function resolveRequestId(req: Request, resolver?: CommerceRequestIdResolver): string {
-  const supplied = resolver?.(req);
-  return supplied && REQUEST_ID_PATTERN.test(supplied) ? supplied : randomUUID();
+/** What `createCommerceRouter` stores in `res.locals` for its routes. */
+export interface CommerceObservabilityLocals {
+  commerceLogger?: CommerceLogger;
+  commerceRequestIdResolver?: CommerceRequestIdResolver;
+  commerceRequestId?: string;
 }
 
-function requestIdFor(req: Request, res: Response): string {
-  const existing: unknown = res.locals.commerceRequestId;
-  if (typeof existing === 'string') return existing;
-  const requestId = resolveRequestId(req);
-  res.locals.commerceRequestId = requestId;
-  return requestId;
+function observabilityLocals(res: Response): CommerceObservabilityLocals {
+  return res.locals as CommerceObservabilityLocals;
 }
 
-function loggerFor(res: Response): CommerceLogger {
-  const logger: unknown = res.locals.commerceLogger;
-  return logger && typeof logger === 'object' && 'error' in logger && typeof logger.error === 'function'
-    ? (logger as CommerceLogger)
-    : consoleCommerceLogger;
+export function resolveRequestId(req: Request, resolver?: CommerceRequestIdResolver): string {
+  let supplied: string | undefined;
+  // A failing host resolver must not prevent the failure response.
+  try {
+    supplied = resolver?.(req);
+  } catch {
+    supplied = undefined;
+  }
+  return typeof supplied === 'string' && REQUEST_ID_PATTERN.test(supplied) ? supplied : randomUUID();
+}
+
+// Resolved only when a failure body needs it, and at most once per request.
+function requestIdFor(req: Request, res: Response): string {
+  const locals = observabilityLocals(res);
+  locals.commerceRequestId ??= resolveRequestId(req, locals.commerceRequestIdResolver);
+  return locals.commerceRequestId;
 }
 
 /**
@@ -59,11 +67,11 @@ export function sendCommerceError(
   res: Response,
   label: string,
   error: unknown,
-  failureFields: Record<string, unknown> = {},
+  { failureFields = {}, classifyUpstreamError }: CommerceRouteOptions = {},
 ): void {
   const resolved: CommerceError | undefined =
     error instanceof UpstreamError
-      ? classifyUpstreamError(error)
+      ? (classifyUpstreamError?.(error) ?? error)
       : error instanceof CommerceError
         ? error
         : undefined;
@@ -81,9 +89,12 @@ export function sendCommerceError(
       ...(resolved?.details ? { details: resolved.details } : {}),
       error,
     };
-    // A failing host logger must not prevent the failure response.
+    // A failing or invalid host logger must not prevent the failure response.
     try {
-      loggerFor(res).error(`commerce-server: ${label}`, context);
+      (observabilityLocals(res).commerceLogger ?? consoleCommerceLogger).error(
+        `commerce-server: ${label}`,
+        context,
+      );
     } catch (loggerError) {
       console.error(`commerce-server: ${label} (host logger failed)`, { ...context, loggerError });
     }
@@ -96,6 +107,11 @@ export function sendCommerceError(
 export interface CommerceRouteOptions {
   /** Fields every failure body carries in addition to `error`, `code`, and `requestId`. */
   failureFields?: Record<string, unknown>;
+  /**
+   * Turns a specific upstream signal into a more precise error. Unclassified upstream failures
+   * are 502. Only routes whose evidence supports a rule should pass one.
+   */
+  classifyUpstreamError?: (error: UpstreamError) => CommerceError;
 }
 
 /** Wraps a route so thrown errors are answered by `sendCommerceError` with the route's label. */
@@ -108,7 +124,7 @@ export function commerceRoute(
     try {
       await handler(req, res);
     } catch (error) {
-      sendCommerceError(req, res, label, error, options.failureFields);
+      sendCommerceError(req, res, label, error, options);
     }
   };
 }
diff --git a/packages/commerce-server/src/lib/commerce/config.ts b/packages/commerce-server/src/lib/commerce/config.ts
index 009565fa..d59b0d41 100644
--- a/packages/commerce-server/src/lib/commerce/config.ts
+++ b/packages/commerce-server/src/lib/commerce/config.ts
@@ -105,17 +105,8 @@ function readOrNotConfigured<T>(read: () => T): T {
   }
 }
 
-export function commerceConfigurationForResponse(res: Response): CommerceConfiguration {
-  const supplied: unknown = res.locals.commerceConfiguration;
-  const configuration: CommerceConfiguration =
-    supplied &&
-    typeof supplied === 'object' &&
-    'read' in supplied &&
-    typeof supplied.read === 'function' &&
-    'readCheckout' in supplied &&
-    typeof supplied.readCheckout === 'function'
-      ? (supplied as CommerceConfiguration)
-      : createRuntimeCommerceConfiguration();
+/** Wraps a configuration so routes and in-process helpers report read failures the same way. */
+export function guardCommerceConfiguration(configuration: CommerceConfiguration): CommerceConfiguration {
   return {
     read: (): CommerceConfig => readOrNotConfigured(() => configuration.read()),
     readCheckout: (): CommerceCheckoutConfiguration =>
@@ -123,6 +114,20 @@ export function commerceConfigurationForResponse(res: Response): CommerceConfigu
   };
 }
 
+export function commerceConfigurationForResponse(res: Response): CommerceConfiguration {
+  const supplied: unknown = res.locals.commerceConfiguration;
+  return guardCommerceConfiguration(
+    supplied &&
+      typeof supplied === 'object' &&
+      'read' in supplied &&
+      typeof supplied.read === 'function' &&
+      'readCheckout' in supplied &&
+      typeof supplied.readCheckout === 'function'
+      ? (supplied as CommerceConfiguration)
+      : createRuntimeCommerceConfiguration(),
+  );
+}
+
 export function readCommerceConfigForResponse(res: Response): CommerceConfig {
   return commerceConfigurationForResponse(res).read();
 }
diff --git a/packages/commerce-server/src/lib/commerce/create-checkout-session.ts b/packages/commerce-server/src/lib/commerce/create-checkout-session.ts
index 9af4c88b..d9b778d4 100644
--- a/packages/commerce-server/src/lib/commerce/create-checkout-session.ts
+++ b/packages/commerce-server/src/lib/commerce/create-checkout-session.ts
@@ -25,7 +25,11 @@ import {
   DEFAULT_CHECKOUT_PAYMENT_METHODS,
   getOAuthAccessToken,
 } from './checkout-subgraph';
-import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './config';
+import {
+  type CommerceConfiguration,
+  createRuntimeCommerceConfiguration,
+  guardCommerceConfiguration,
+} from './config';
 import { InvalidRequestError, UpstreamError } from './errors';
 import { gqlRequest } from './gql';
 
@@ -178,6 +182,7 @@ export async function createCheckoutSession(
     );
   }
 
+  const guardedConfiguration = guardCommerceConfiguration(configuration);
   const {
     storeId,
     channelId,
@@ -187,8 +192,8 @@ export async function createCheckoutSession(
     sourceApp,
     owner,
     currencyCode: configCurrencyCode,
-  } = configuration.read();
-  const checkoutConfiguration = configuration.readCheckout();
+  } = guardedConfiguration.read();
+  const checkoutConfiguration = guardedConfiguration.readCheckout();
   const enablePromotionCodes: boolean = promotionCodesEnabled(checkoutConfiguration);
   const catalogShippingEnabled: boolean = lineItemData === undefined && checkoutConfiguration.enableShipping;
   const checkoutOAuthScope: string = 'commerce.product:read';
diff --git a/packages/commerce-server/src/lib/commerce/get-order-status.ts b/packages/commerce-server/src/lib/commerce/get-order-status.ts
index c59d757e..9c7575c8 100644
--- a/packages/commerce-server/src/lib/commerce/get-order-status.ts
+++ b/packages/commerce-server/src/lib/commerce/get-order-status.ts
@@ -3,7 +3,11 @@
  * Unlike the storefront cart API, this endpoint includes completed orders.
  */
 import { authorizationHeaders, getOAuthAccessToken } from './checkout-subgraph';
-import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './config';
+import {
+  type CommerceConfiguration,
+  createRuntimeCommerceConfiguration,
+  guardCommerceConfiguration,
+} from './config';
 import { InvalidRequestError, NotFoundError, UpstreamError } from './errors';
 import type { Money } from './gql';
 
@@ -85,7 +89,8 @@ export async function getOrderStatus(
     throw new InvalidOrderIdError();
   }
 
-  const { storeId, channelId, clientId, clientSecret, apiBaseUrl, currencyCode } = configuration.read();
+  const { storeId, channelId, clientId, clientSecret, apiBaseUrl, currencyCode } =
+    guardCommerceConfiguration(configuration).read();
   const token = await getOAuthAccessToken({
     clientId,
     clientSecret,
@@ -104,7 +109,10 @@ export async function getOrderStatus(
       cache: 'no-store',
     });
   } catch (cause) {
-    throw new UpstreamError('Order lookup could not reach Commerce', { cause });
+    throw new UpstreamError('Order lookup could not reach Commerce', {
+      cause,
+      details: { endpoint: endpoint.href },
+    });
   }
   if (!response.ok) {
     // The Orders API reports a missing order as 404 NOT_FOUND and an ID it can't decode as 422
@@ -117,7 +125,7 @@ export async function getOrderStatus(
     if (response.status === 422 && code === 'VALIDATION_FAILED') throw new InvalidOrderIdError();
     throw new UpstreamError(`Failed to load order: upstream returned ${response.status}`, {
       unauthorized: response.status === 401 || response.status === 403,
-      details: { upstreamStatus: response.status },
+      details: { endpoint: endpoint.href, upstreamStatus: response.status, upstreamCode: code ?? undefined },
     });
   }
 
@@ -125,7 +133,10 @@ export async function getOrderStatus(
   try {
     data = (await response.json()) as OrderResponse;
   } catch (cause) {
-    throw new UpstreamError('Order lookup returned a non-JSON response', { cause });
+    throw new UpstreamError('Order lookup returned a non-JSON response', {
+      cause,
+      details: { endpoint: endpoint.href },
+    });
   }
   const order = data?.order;
   const context = order?.context;
@@ -137,7 +148,9 @@ export async function getOrderStatus(
     !isBindingId(context?.storeId) ||
     !isBindingId(context?.channelId)
   ) {
-    throw new UpstreamError('Order lookup did not return the requested order');
+    throw new UpstreamError('Order lookup did not return the requested order', {
+      details: { endpoint: endpoint.href },
+    });
   }
   // Report an order bound to another store or channel as missing so the route doesn't reveal it exists.
   if (context.storeId !== storeId || context.channelId !== channelId) {
diff --git a/packages/commerce-server/src/lib/commerce/upstream-errors.ts b/packages/commerce-server/src/lib/commerce/upstream-errors.ts
index ba46c4b6..5d6dfe7b 100644
--- a/packages/commerce-server/src/lib/commerce/upstream-errors.ts
+++ b/packages/commerce-server/src/lib/commerce/upstream-errors.ts
@@ -1,5 +1,7 @@
 /**
  * Known upstream failures that mean something more specific than "Commerce failed" (502).
+ * Routes opt in through `commerceRoute`'s `classifyUpstreamError`, so a rule only applies where
+ * its evidence does.
  *
  * Add a rule only with evidence of how Commerce reports the case, plus a test. Unmatched
  * upstream errors stay 502; the server log carries their codes and statuses so new rules can
@@ -37,7 +39,7 @@ interface UpstreamErrorRule {
   toError(error: UpstreamError): CommerceError;
 }
 
-const UPSTREAM_ERROR_RULES: readonly UpstreamErrorRule[] = [
+const CART_UPSTREAM_ERROR_RULES: readonly UpstreamErrorRule[] = [
   {
     // A completed (paid) draft is reported the same way, so this is "no longer a usable cart".
     matches: isCartNotFoundError,
@@ -45,6 +47,7 @@ const UPSTREAM_ERROR_RULES: readonly UpstreamErrorRule[] = [
   },
 ];
 
-export function classifyUpstreamError(error: UpstreamError): CommerceError {
-  return UPSTREAM_ERROR_RULES.find((rule) => rule.matches(error))?.toError(error) ?? error;
+/** For routes acting on an existing saved cart (`/cart/:id`); creating a cart has none to miss. */
+export function classifyCartUpstreamError(error: UpstreamError): CommerceError {
+  return CART_UPSTREAM_ERROR_RULES.find((rule) => rule.matches(error))?.toError(error) ?? error;
 }
diff --git a/packages/commerce-server/src/router.test.ts b/packages/commerce-server/src/router.test.ts
index d9a9d1bf..35c0f43b 100644
--- a/packages/commerce-server/src/router.test.ts
+++ b/packages/commerce-server/src/router.test.ts
@@ -486,6 +486,25 @@ describe('Commerce scoped routes', () => {
     },
   );
 
+  // The cart-not-found rule only applies to routes acting on an existing saved cart.
+  it.each([
+    ['products', readProducts, []],
+    ['create cart (adding the first item)', createCart, [{ addDraftOrder: { id: 'cart-new' } }]],
+  ] as const)(
+    'returns 502, not cart not found, when %s receives "Order not found"',
+    async (_name, handler, before): Promise<void> => {
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+      for (const result of before) vi.mocked(gqlRequest).mockResolvedValueOnce(result);
+      vi.mocked(gqlRequest).mockRejectedValueOnce(
+        new GraphQLErrorWithCodes([{ code: 'INTERNAL_SERVER_ERROR', message: 'Order not found' }]),
+      );
+      const res = response();
+      await handler(scopedRequest, res as unknown as Response);
+      expect(res.status).toHaveBeenCalledWith(502);
+      expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ code: 'upstream_error' }));
+    },
+  );
+
   it('reports a mixed not-found and embedded 403 as upstream_unauthorized without clearing the cart', async (): Promise<void> => {
     vi.spyOn(console, 'error').mockImplementation(() => {});
     vi.mocked(gqlRequest).mockRejectedValueOnce(
@@ -623,6 +642,29 @@ describe('Commerce router mounting', (): void => {
     );
   });
 
+  it('falls back to a generated id when getRequestId throws', async (): Promise<void> => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const result = await requestThroughRouter(
+      createCommerceCatalogRouter(failingConfiguration, {
+        getRequestId: (req): string => (req.get('x-request-id') as string).trim(),
+      }),
+      '/config',
+    );
+    expect(result.status).toBe(503);
+    const { requestId } = (await result.json()) as { requestId: string };
+    expect(requestId).toMatch(/^[0-9a-f-]{36}$/);
+  });
+
+  it('does not resolve a request id for a successful request', async (): Promise<void> => {
+    const getRequestId = vi.fn((): string => 'edge-123');
+    const result = await requestThroughRouter(
+      createCommerceCatalogRouter(configuration, { getRequestId }),
+      '/config',
+    );
+    expect(result.status).toBe(200);
+    expect(getRequestId).not.toHaveBeenCalled();
+  });
+
   it.each([
     ['a valid host id', 'edge-123', 'edge-123'],
     ['an id with unsafe characters', 'id with spaces; level=error', undefined],
diff --git a/packages/commerce-server/src/router.ts b/packages/commerce-server/src/router.ts
index 8e7a54e8..93508768 100644
--- a/packages/commerce-server/src/router.ts
+++ b/packages/commerce-server/src/router.ts
@@ -5,9 +5,9 @@ import {
 } from './lib/commerce/checkout-return-urls';
 import {
   type CommerceLogger,
+  type CommerceObservabilityLocals,
   type CommerceRequestIdResolver,
   consoleCommerceLogger,
-  resolveRequestId,
 } from './lib/commerce/commerce-route';
 import { type CommerceConfiguration, createRuntimeCommerceConfiguration } from './lib/commerce/config';
 import cartDiscountPost from './server/api/commerce/cart/[id]/discounts/POST';
@@ -58,10 +58,12 @@ export function createCommerceRouter(options: CreateCommerceRouterOptions = {}):
     ? createCheckoutReturnUrlValidator(options.checkoutReturnUrls)
     : undefined;
 
-  router.use((req, res, next): void => {
-    const requestId: string = resolveRequestId(req, options.getRequestId);
-    res.locals.commerceRequestId = requestId;
-    res.locals.commerceLogger = logger;
+  router.use((_req, res, next): void => {
+    const observability: CommerceObservabilityLocals = {
+      commerceLogger: logger,
+      commerceRequestIdResolver: options.getRequestId,
+    };
+    Object.assign(res.locals, observability);
     res.locals.commerceConfiguration = configuration;
     res.locals.commerceCheckoutReturnUrlValidator = validateCheckoutReturnUrls;
     next();
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
index 58a2fbb2..78200f4f 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/GET.ts
@@ -27,7 +27,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
-import { isCartNotFoundError } from '@/lib/commerce/upstream-errors';
+import { classifyCartUpstreamError, isCartNotFoundError } from '@/lib/commerce/upstream-errors';
 
 async function readCart(req: Request, res: Response): Promise<void> {
   const cartId: unknown = req.params.id;
@@ -61,4 +61,6 @@ async function readCart(req: Request, res: Response): Promise<void> {
   res.json({ cart: data.orderById ?? null });
 }
 
-export default commerceRoute('Failed to load cart', readCart);
+export default commerceRoute('Failed to load cart', readCart, {
+  classifyUpstreamError: classifyCartUpstreamError,
+});
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
index 684f39ae..c0ae58e4 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/discounts/POST.ts
@@ -27,6 +27,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { classifyCartUpstreamError } from '@/lib/commerce/upstream-errors';
 
 const applyDiscountCodesMutation = `
   mutation ApplyDiscountCodes($input: ApplyDiscountCodesInput!) {
@@ -78,4 +79,6 @@ async function applyDiscountCodes(req: Request, res: Response): Promise<void> {
   res.json({ cart: hydrated.orderById ?? null });
 }
 
-export default commerceRoute('Failed to apply discount codes', applyDiscountCodes);
+export default commerceRoute('Failed to apply discount codes', applyDiscountCodes, {
+  classifyUpstreamError: classifyCartUpstreamError,
+});
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
index 5c4be0ae..0731bff9 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/POST.ts
@@ -30,6 +30,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { classifyCartUpstreamError } from '@/lib/commerce/upstream-errors';
 
 const addLineItemBySkuIdMutation = `
   mutation AddLineItemBySkuId($input: AddLineItemInput!) {
@@ -82,4 +83,6 @@ async function addLineItem(req: Request, res: Response): Promise<void> {
   res.status(201).json({ cart: hydrated.orderById ?? null });
 }
 
-export default commerceRoute('Failed to add line item', addLineItem);
+export default commerceRoute('Failed to add line item', addLineItem, {
+  classifyUpstreamError: classifyCartUpstreamError,
+});
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
index 5715596f..ac48726d 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
@@ -24,6 +24,7 @@ import {
   getCartOrderQuery,
   orderStorefrontEndpoint,
 } from '@/lib/commerce/order-subgraph';
+import { classifyCartUpstreamError } from '@/lib/commerce/upstream-errors';
 
 const deleteLineItemByIdMutation = `
   mutation DeleteLineItemById($id: ID!, $orderId: ID!) {
@@ -61,4 +62,6 @@ async function deleteLineItem(req: Request, res: Response): Promise<void> {
   res.json({ cart: hydrated.orderById ?? null });
 }
 
-export default commerceRoute('Failed to delete line item', deleteLineItem);
+export default commerceRoute('Failed to delete line item', deleteLineItem, {
+  classifyUpstreamError: classifyCartUpstreamError,
+});
diff --git a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
index 1af9cb32..38ed496f 100644
--- a/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
+++ b/packages/commerce-server/src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
@@ -28,6 +28,7 @@ import {
   type UpdateLineItemByIdResult,
   type UpdateLineItemByIdVariables,
 } from '@/lib/commerce/order-subgraph';
+import { classifyCartUpstreamError } from '@/lib/commerce/upstream-errors';
 
 const updateLineItemByIdMutation = `
   mutation UpdateLineItemById($input: UpdateLineItemByIdInput!) {
@@ -81,4 +82,6 @@ async function updateLineItem(req: Request, res: Response): Promise<void> {
   res.json({ cart: hydrated.orderById ?? null });
 }
 
-export default commerceRoute('Failed to update line item', updateLineItem);
+export default commerceRoute('Failed to update line item', updateLineItem, {
+  classifyUpstreamError: classifyCartUpstreamError,
+});