fix: surface relayer/edge error messages on 401 and 403 (0.4.x) (#452)

* fix: surface relayer/edge error messages on 401 and 403

The V2 request engine assumed the reason for auth failures instead of
passing through the message returned by the relayer or an intermediary
(Cloudflare/Kong):

- 401 hardcoded "Unauthorized, missing or invalid Zama Fhevm API Key."
  and never read the response body.
- 403 (e.g. a Cloudflare/Kong edge block for a missing x-api-key header)
  was not handled at all and surfaced as "Unexpected response status 403",
  discarding the body.

Both paths now read the response body (best-effort: relayer JSON
`{ error: { message, label } }`, flat `{ message, label }`, or plain text)
and surface the provided message, falling back to the previous default
only when the body has nothing usable. No public type changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: surface relayer/edge error messages in shared fetch error path

`throwRelayerResponseError` (src/relayer/error.ts) — used by
AbstractRelayerProvider for the keyurl GET on both the V1 and V2 providers,
and by the V1 input-proof path — assumed the reason for a failure and
discarded the response body's message. A 403 edge block (Cloudflare/Kong)
or a 401/404 from Kong therefore surfaced only a generic
"HTTP error! status: <code>".

It now reads the body once (relayer JSON `{ error: { message } }`, flat
`{ message }`, or plain text) and appends the provided message, while still
preserving the parsed body in the error cause.

Tests: V1 401/403 surfacing; the keyurl 404+Kong-body test now asserts the
surfaced "no Route matched with those values" message.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: only surface JSON error messages, not raw text bodies

Relayer/edge (Cloudflare/Kong) errors that carry a message are JSON, so the
best-effort readers now surface a message only when the body parses as JSON.
For non-JSON bodies they leave the previous behaviour unchanged (no appended
text, empty `responseJson` in the cause) — avoiding noise like a plain
"Forbidden"/"Rate Limit" body or an HTML error page leaking into the message.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: drop stale 'falls through' comments after 401 break

The 401 case now ends with an explicit break, so the following 429/404
cases no longer fall through to.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: bump version to 0.4.4

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: fix dead Relayer SDK docs link (404 -> docs.zama.org/protocol)

The /protocol/relayer-sdk-guides section index returns 404 to crawlers
(GitBook SPA), failing the linkspector CI check. Point to the protocol
docs root, which resolves.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: regenerate src/_version.ts for 0.4.4

Run `npm run version` so src/_version.ts matches package.json (was stale
at 0.4.2); it feeds the version string into SDK error messages.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: poppyseedDev

docs/initialization.md

@@ -72,7 +72,7 @@ const instance = await createInstance({
 ```
 
 {% hint style="info" %}
-For more information on the Relayer's part, please refer to [the Relayer SDK documentation](https://docs.zama.org/protocol/relayer-sdk-guides).
+For more information on the Relayer's part, please refer to [the Relayer SDK documentation](https://docs.zama.org/protocol).
 {% endhint %}
 
 # Network Configuration

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zama-fhe/relayer-sdk",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "fhevm Relayer SDK",
   "main": "lib/node.js",
   "types": "lib/node.d.ts",

src/_version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated
-export const version: string = '0.4.2';
+export const version: string = '0.4.4';
 export const sdkName: string = '@zama-fhe/relayer-sdk';

src/relayer-provider/v1/RelayerV1Provider.test.ts

@@ -119,3 +119,48 @@ describeIfFetchMock('RelayerV1Provider - Auth on GET requests', () => {
     expect(headers['x-api-key']).toBeUndefined();
   });
 });
+
+////////////////////////////////////////////////////////////////////////////////
+// Error message surfacing (401 / 403)
+////////////////////////////////////////////////////////////////////////////////
+
+describeIfFetchMock('RelayerV1Provider - error message surfacing', () => {
+  const relayerUrlV1 = `${SepoliaConfig.relayerUrl!}/v1`;
+
+  beforeEach(() => {
+    fetchMock.removeRoutes();
+  });
+
+  it('v1: surfaces a 403 (edge/gateway) error message', async () => {
+    // Cloudflare/Kong style flat `{ message, label }` body.
+    fetchMock.get(`${relayerUrlV1}/keyurl`, {
+      status: 403,
+      body: {
+        message: 'Unauthorized. Missing or invalid Zama API Key',
+        label: 'unauthorized',
+      },
+    });
+
+    const provider = new RelayerV1Provider({ relayerUrl: relayerUrlV1 });
+    await expect(provider.fetchGetKeyUrl()).rejects.toThrow(
+      'Unauthorized. Missing or invalid Zama API Key',
+    );
+  });
+
+  it('v1: surfaces a 401 relayer error message', async () => {
+    fetchMock.get(`${relayerUrlV1}/keyurl`, {
+      status: 401,
+      body: {
+        error: {
+          message: 'API key not passed via x-api-key header',
+          label: 'unauthorized',
+        },
+      },
+    });
+
+    const provider = new RelayerV1Provider({ relayerUrl: relayerUrlV1 });
+    await expect(provider.fetchGetKeyUrl()).rejects.toThrow(
+      'API key not passed via x-api-key header',
+    );
+  });
+});

src/relayer-provider/v2/RelayerV2AsyncRequest.test.ts

@@ -383,3 +383,75 @@ describeIfFetchMock('RelayerV2AsyncRequest - Auth on GET requests', () => {
     expect(getHeaders['x-api-key']).toBeUndefined();
   });
 });
+
+////////////////////////////////////////////////////////////////////////////////
+// Auth error message surfacing (401 / 403)
+////////////////////////////////////////////////////////////////////////////////
+
+describeIfFetchMock('RelayerV2AsyncRequest - auth error surfacing', () => {
+  beforeEach(() => {
+    fetchMock.removeRoutes();
+    fetchMock.callHistory.clear();
+  });
+
+  afterAll(async () => {
+    await fetchMock.callHistory.flush(true);
+  });
+
+  it('v2: 401 surfaces the relayer-provided error message', async () => {
+    fetchMock.post(requestUrl, {
+      status: 401,
+      body: {
+        error: {
+          label: 'unauthorized',
+          message: 'API key not passed via x-api-key header',
+        },
+      },
+    });
+
+    const relayerRequest = new RelayerV2AsyncRequest({
+      relayerOperation: 'INPUT_PROOF',
+      url: requestUrl,
+      payload,
+    });
+
+    await expect(relayerRequest.run()).rejects.toThrow(
+      'API key not passed via x-api-key header',
+    );
+  });
+
+  it('v2: 403 (edge/gateway) surfaces the provided error message', async () => {
+    // Cloudflare/Kong style flat `{ message, label }` body.
+    fetchMock.post(requestUrl, {
+      status: 403,
+      body: {
+        message: 'Unauthorized. Missing or invalid Zama API Key',
+        label: 'unauthorized',
+      },
+    });
+
+    const relayerRequest = new RelayerV2AsyncRequest({
+      relayerOperation: 'INPUT_PROOF',
+      url: requestUrl,
+      payload,
+    });
+
+    await expect(relayerRequest.run()).rejects.toThrow(
+      'Unauthorized. Missing or invalid Zama API Key',
+    );
+  });
+
+  it('v2: 401 without a body falls back to the default message', async () => {
+    fetchMock.post(requestUrl, { status: 401 });
+
+    const relayerRequest = new RelayerV2AsyncRequest({
+      relayerOperation: 'INPUT_PROOF',
+      url: requestUrl,
+      payload,
+    });
+
+    await expect(relayerRequest.run()).rejects.toThrow(
+      'Unauthorized, missing or invalid Zama Fhevm API Key.',
+    );
+  });
+});

src/relayer-provider/v2/RelayerV2AsyncRequest.ts

@@ -55,7 +55,11 @@ import {
   assertIsRelayerV2GetResponseQueued,
   assertIsRelayerV2PostResponseQueued,
 } from './guards/RelayerV2ResponseQueued';
-import { isNonEmptyString, safeJSONstringify } from '@base/string';
+import {
+  isNonEmptyString,
+  isRecordStringProperty,
+  safeJSONstringify,
+} from '@base/string';
 import { sdkName, version } from '../../_version';
 import { RelayerV2TimeoutError } from './errors/RelayerV2TimeoutError';
 import { RelayerV2AbortError } from './errors/RelayerV2AbortError';
@@ -483,6 +487,13 @@ export class RelayerV2AsyncRequest {
 
       // At this stage: `terminated` is guaranteed to be `false`.
 
+      // 403 is not part of the relayer's typed response set — it is an
+      // edge/gateway rejection (e.g. Cloudflare/Kong). Surface its body message
+      // before narrowing to the relayer status union.
+      if (response.status === 403) {
+        await this._throwForbiddenError(response);
+      }
+
       const responseStatus: RelayerV2PostResponseStatus =
         response.status as RelayerV2PostResponseStatus;
 
@@ -558,11 +569,14 @@ export class RelayerV2AsyncRequest {
         // RelayerV2ApiError401
         // falls through
         case 401: {
-          this._throwUnauthorizedError(responseStatus);
+          await this._throwUnauthorizedError(response, responseStatus);
+          // `_throwUnauthorizedError` always throws; `break` only satisfies the
+          // compiler's switch fallthrough check (awaiting a `Promise<never>` is
+          // not recognised as terminating).
+          break;
         }
         // RelayerV2ResponseFailed
         // RelayerV2ApiError429
-        // falls through
         case 429: {
           // Retry
           // Rate Limit error (Cloudflare/Kong/Relayer), reason in message
@@ -707,6 +721,13 @@ export class RelayerV2AsyncRequest {
 
       // At this stage: `terminated` is guaranteed to be `false`.
 
+      // 403 is not part of the relayer's typed response set — it is an
+      // edge/gateway rejection (e.g. Cloudflare/Kong). Surface its body message
+      // before narrowing to the relayer status union.
+      if (response.status === 403) {
+        await this._throwForbiddenError(response);
+      }
+
       const responseStatus: RelayerV2GetResponseStatus =
         response.status as RelayerV2GetResponseStatus;
 
@@ -926,9 +947,12 @@ export class RelayerV2AsyncRequest {
         }
         // falls through
         case 401: {
-          this._throwUnauthorizedError(responseStatus);
+          await this._throwUnauthorizedError(response, responseStatus);
+          // `_throwUnauthorizedError` always throws; `break` only satisfies the
+          // compiler's switch fallthrough check (awaiting a `Promise<never>` is
+          // not recognised as terminating).
+          break;
         }
-        // falls through
         case 404: {
           // Abort
           // Wrong jobId, incorrect format or unknown value etc.
@@ -1578,18 +1602,97 @@ export class RelayerV2AsyncRequest {
    * Throws an unauthorized error for 401 responses.
    * @throws {RelayerV2ResponseApiError} Always throws with 'unauthorized' label.
    */
-  private _throwUnauthorizedError(
+  private async _throwUnauthorizedError(
+    response: Response,
     status: Extract<RelayerFailureStatus, 401>,
-  ): never {
+  ): Promise<never> {
+    // Surface the message provided by the relayer or an intermediary
+    // (e.g. Kong) instead of assuming the reason for the 401.
+    const { message } = await this._readResponseErrorMessage(response);
     this._throwRelayerV2ResponseApiError({
       status,
       relayerApiError: {
         label: 'unauthorized',
-        message: 'Unauthorized, missing or invalid Zama Fhevm API Key.',
+        message: isNonEmptyString(message)
+          ? message
+          : 'Unauthorized, missing or invalid Zama Fhevm API Key.',
       },
     });
   }
 
+  /**
+   * Throws a 403 error.
+   *
+   * 403 is not part of the relayer's typed response set — it indicates the
+   * request was blocked by an edge/gateway (e.g. Cloudflare or Kong) before
+   * reaching the relayer, most commonly because of a missing or invalid
+   * `x-api-key` header. Surface the message provided by the intermediary
+   * instead of a generic "unexpected status".
+   * @throws {RelayerV2ResponseStatusError} Always throws.
+   */
+  private async _throwForbiddenError(response: Response): Promise<never> {
+    const { message } = await this._readResponseErrorMessage(response);
+    throw new RelayerV2ResponseStatusError({
+      fetchMethod: this._fetchMethod!,
+      status: 403,
+      url: this._url,
+      jobId: this._jobId,
+      operation: this._relayerOperation,
+      elapsed: this._elapsed,
+      retryCount: this._retryCount,
+      state: { ...this._state },
+      ...(isNonEmptyString(message) ? { details: message } : {}),
+    });
+  }
+
+  /**
+   * Best-effort extraction of the error message and label provided by the
+   * relayer or an intermediary (e.g. Cloudflare or Kong). The body may be a
+   * relayer JSON error (`{ error: { message, label } }`), a flat
+   * `{ message, label }`, or plain text. Never throws — returns `{}` when
+   * nothing usable can be read.
+   */
+  private async _readResponseErrorMessage(
+    response: Response,
+  ): Promise<{ message?: string | undefined; label?: string | undefined }> {
+    let text: string;
+    try {
+      text = await response.text();
+    } catch {
+      return {};
+    }
+
+    if (!isNonEmptyString(text)) {
+      return {};
+    }
+
+    try {
+      const json: unknown = JSON.parse(text);
+      // Relayer errors are nested under `error`; edge/gateway errors
+      // (Cloudflare/Kong) are usually flat `{ message, label }`.
+      const err: unknown =
+        typeof json === 'object' && json !== null && 'error' in json
+          ? (json as { error: unknown }).error
+          : json;
+
+      const message = isRecordStringProperty(err, 'message')
+        ? err.message
+        : undefined;
+      const label = isRecordStringProperty(err, 'label')
+        ? err.label
+        : undefined;
+
+      if (message !== undefined || label !== undefined) {
+        return { message, label };
+      }
+    } catch {
+      // Body was not JSON — relayer/edge errors that carry a message are JSON,
+      // so there is nothing usable to surface.
+    }
+
+    return {};
+  }
+
   /**
    * Throws a relayer API error with the given status and error details.
    * @throws {RelayerV2ResponseApiError} Always throws with the provided error details.

src/relayer-provider/v2/RelayerV2Provider_keyurl.test.ts

@@ -234,8 +234,11 @@ describeIfFetchMock('RelayerV2Provider', () => {
         'Expected fetchGetKeyUrl to throw an error, but it did not.',
       );
     } catch (e) {
-      // Error message
-      expect(String(e)).toStrictEqual('Error: HTTP error! status: 404');
+      // Error message — the message provided by the relayer/intermediary
+      // (here Kong's "no Route matched with those values") is now surfaced.
+      expect(String(e)).toStrictEqual(
+        'Error: HTTP error! status: 404 no Route matched with those values',
+      );
 
       // Error cause
       const cause = getErrorCause(e) as any;

src/relayer-provider/v2/errors/RelayerV2ResponseStatusError.ts

@@ -15,6 +15,11 @@ export type RelayerV2ResponseStatusErrorType = RelayerV2ResponseStatusError & {
 export type RelayerV2ResponseStatusErrorParams = Prettify<
   Omit<RelayerV2ResponseErrorBaseParams, keyof RelayerErrorBaseParams> & {
     state: RelayerV2AsyncRequestState;
+    /**
+     * Optional message provided by the relayer or an intermediary
+     * (e.g. Cloudflare/Kong) for the unexpected status, surfaced as `Details:`.
+     */
+    details?: string | undefined;
   }
 >;