Gracefully handle OpenAPI fetch errors

packages/gitbook/src/lib/openapi/fetch.ts

@@ -1,6 +1,11 @@
-import { OpenAPIParseError, parseOpenAPI } from '@gitbook/openapi-parser';
+import {
+    type Filesystem,
+    OpenAPIParseError,
+    type OpenAPIParseErrorCode,
+    parseOpenAPI,
+} from '@gitbook/openapi-parser';
 
-import { noCacheFetchOptions } from '@/lib/data';
+import { DataFetcherError, noCacheFetchOptions } from '@/lib/data';
 import { resolveContentRef } from '@/lib/references';
 import { unstable_cacheLife as cacheLife } from 'next/cache';
 import { assert } from 'ts-essentials';
@@ -48,18 +53,35 @@ export async function fetchOpenAPIFilesystem(
     };
 }
 
-const fetchFilesystem = async (url: string) => {
+const fetchFilesystem = async (
+    url: string
+): Promise<
+    | Filesystem
+    | {
+          error: {
+              code: OpenAPIParseErrorCode;
+              message: string;
+          };
+      }
+> => {
     'use cache';
     try {
         return await fetchFilesystemUncached(url);
     } catch (error) {
+        // To avoid hammering the file with requests, we cache the error for around a minute.
+        cacheLife('minutes');
         // Throwing an error inside a "use cache" function obfuscates the error,
         // so we need to handle it here and recreates the error outside the cache function.
         if (error instanceof OpenAPIParseError) {
-            cacheLife('seconds');
             return { error: { code: error.code, message: error.message } };
         }
-        throw error;
+        if (error instanceof DataFetcherError) {
+            return { error: { code: 'invalid' as const, message: 'Failed to fetch OpenAPI file' } };
+        }
+        // If the error is not an OpenAPIParseError or DataFetcherError,
+        // we assume it's an unknown error and return a generic error.
+        console.error('Unknown error while fetching OpenAPI file:', error);
+        return { error: { code: 'invalid' as const, message: 'Unknown error' } };
     }
 };
 
@@ -78,7 +100,7 @@ async function fetchFilesystemUncached(
     });
 
     if (!response.ok) {
-        throw new Error(`Failed to fetch OpenAPI file: ${response.status} ${response.statusText}`);
+        throw new DataFetcherError('Failed to fetch OpenAPI file', response.status);
     }
 
     const text = await response.text();

packages/openapi-parser/src/error.ts

@@ -1,6 +1,6 @@
 import type { ErrorObject } from '@scalar/openapi-parser';
 
-type OpenAPIParseErrorCode =
+export type OpenAPIParseErrorCode =
     | 'invalid'
     | 'parse-v2-in-v3'
     | 'v2-conversion'