Raise ParseError if non-200 response returns invalid JSON (#1320)

atainter · web-flow · commit 94871daf4da1 · 2025-07-25T15:16:14.000-07:00
## Description Missed a codepath in #1313 where non-200 responses would attempt to parse the body
diff --git a/src/common/exceptions/parse-error.ts b/src/common/exceptions/parse-error.ts
@@ -4,11 +4,23 @@ export class ParseError extends Error implements RequestException {
   readonly name = 'ParseError';
   readonly status = 500;
   readonly rawBody: string;
+  readonly rawStatus: number;
   readonly requestID: string;
 
-  constructor(message: string, rawBody: string, requestID: string) {
+  constructor({
+    message,
+    rawBody,
+    rawStatus,
+    requestID,
+  }: {
+    message: string;
+    rawBody: string;
+    requestID: string;
+    rawStatus: number;
+  }) {
     super(message);
     this.rawBody = rawBody;
+    this.rawStatus = rawStatus;
     this.requestID = requestID;
   }
 }
diff --git a/src/common/net/fetch-client.spec.ts b/src/common/net/fetch-client.spec.ts
@@ -1,6 +1,7 @@
 import fetch from 'jest-fetch-mock';
 import { fetchOnce, fetchURL } from '../../common/utils/test-utils';
 import { FetchHttpClient } from './fetch-client';
+import { ParseError } from '../exceptions/parse-error';
 
 const fetchClient = new FetchHttpClient('https://test.workos.com', {
   headers: {
@@ -224,4 +225,82 @@ describe('Fetch client', () => {
       expect(await response.toJSON()).toEqual({ data: 'response' });
     });
   });
+
+  describe('error handling', () => {
+    it('should throw ParseError when response body is not valid JSON on non-200 status', async () => {
+      // Mock a 500 response with invalid JSON (like an HTML error page)
+      fetch.mockResponseOnce(
+        '<html><body>Internal Server Error</body></html>',
+        {
+          status: 500,
+          statusText: 'Internal Server Error',
+          headers: {
+            'X-Request-ID': 'test-request-123',
+            'Content-Type': 'text/html',
+          },
+        },
+      );
+
+      await expect(fetchClient.get('/users', {})).rejects.toThrow(ParseError);
+
+      try {
+        await fetchClient.get('/users', {});
+      } catch (error) {
+        expect(error).toBeInstanceOf(ParseError);
+        const parseError = error as ParseError;
+        expect(parseError.message).toContain('Unexpected token');
+        expect(parseError.rawBody).toBe(
+          '<html><body>Internal Server Error</body></html>',
+        );
+        expect(parseError.requestID).toBe('test-request-123');
+        expect(parseError.rawStatus).toBe(500);
+      }
+    });
+
+    it('should throw ParseError for non-FGA endpoints with invalid JSON response', async () => {
+      // Test with a non-FGA endpoint to ensure the error handling works for regular requests too
+      fetch.mockResponseOnce('Not JSON content', {
+        status: 400,
+        statusText: 'Bad Request',
+        headers: {
+          'X-Request-ID': 'bad-request-456',
+          'Content-Type': 'text/plain',
+        },
+      });
+
+      await expect(
+        fetchClient.post('/organizations', { name: 'Test' }, {}),
+      ).rejects.toThrow(ParseError);
+
+      try {
+        await fetchClient.post('/organizations', { name: 'Test' }, {});
+      } catch (error) {
+        expect(error).toBeInstanceOf(ParseError);
+        const parseError = error as ParseError;
+        expect(parseError.rawBody).toBe('Not JSON content');
+        expect(parseError.requestID).toBe('bad-request-456');
+        expect(parseError.rawStatus).toBe(400);
+      }
+    });
+
+    it('should throw ParseError when X-Request-ID header is missing', async () => {
+      fetch.mockResponseOnce('Invalid JSON Response', {
+        status: 422,
+        statusText: 'Unprocessable Entity',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      try {
+        await fetchClient.put('/users/123', { name: 'Updated' }, {});
+      } catch (error) {
+        expect(error).toBeInstanceOf(ParseError);
+        const parseError = error as ParseError;
+        expect(parseError.rawBody).toBe('Invalid JSON Response');
+        expect(parseError.requestID).toBe(''); // Should default to empty string when header is missing
+        expect(parseError.rawStatus).toBe(422);
+      }
+    });
+  });
 });
diff --git a/src/common/net/fetch-client.ts b/src/common/net/fetch-client.ts
@@ -6,6 +6,7 @@ import {
   ResponseHeaders,
 } from '../interfaces/http-client.interface';
 import { HttpClient, HttpClientError, HttpClientResponse } from './http-client';
+import { ParseError } from '../exceptions/parse-error';
 
 export class FetchHttpClient extends HttpClient implements HttpClientInterface {
   private readonly _fetchFn;
@@ -181,16 +182,34 @@ export class FetchHttpClient extends HttpClient implements HttpClientInterface {
     });
 
     if (!res.ok) {
+      const requestID = res.headers.get('X-Request-ID') ?? '';
+      const rawBody = await res.text();
+
+      let responseJson: any;
+
+      try {
+        responseJson = JSON.parse(rawBody);
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          throw new ParseError({
+            message: error.message,
+            rawBody,
+            requestID,
+            rawStatus: res.status,
+          });
+        }
+        throw error;
+      }
+
       throw new HttpClientError({
         message: res.statusText,
         response: {
           status: res.status,
           headers: res.headers,
-          data: await res.json(),
+          data: responseJson,
         },
       });
     }
-
     return new FetchHttpClientResponse(res);
   }
 
diff --git a/src/workos.ts b/src/workos.ts
@@ -278,8 +278,14 @@ export class WorkOS {
     if (error instanceof SyntaxError) {
       const rawResponse = res.getRawResponse() as Response;
       const requestID = rawResponse.headers.get('X-Request-ID') ?? '';
+      const rawStatus = rawResponse.status;
       const rawBody = await rawResponse.text();
-      throw new ParseError(error.message, rawBody, requestID);
+      throw new ParseError({
+        message: error.message,
+        rawBody,
+        rawStatus,
+        requestID,
+      });
     }
   }
 
