Show error summary from API when transcript fails to load

via/static/scripts/video_player/components/TranscriptError.tsx

@@ -0,0 +1,20 @@
+import type { APIError } from '../utils/api';
+
+export type TranscriptErrorProps = {
+  error: APIError;
+};
+
+export default function TranscriptError({ error }: TranscriptErrorProps) {
+  return (
+    <div className="p-3">
+      <h2 className="text-lg">Unable to load transcript</h2>
+      <p className="mb-3">{error.error?.title ?? error.message}</p>
+      {error.error?.detail && (
+        <details>
+          <summary className="mb-2">Error details:</summary>
+          <p>{error.error.detail}</p>
+        </details>
+      )}
+    </div>
+  );
+}

via/static/scripts/video_player/components/VideoPlayerApp.tsx

@@ -26,6 +26,7 @@ import { formatTranscript, mergeSegments } from '../utils/transcript';
 import HypothesisClient from './HypothesisClient';
 import Transcript from './Transcript';
 import type { TranscriptControls } from './Transcript';
+import TranscriptError from './TranscriptError';
 import YouTubeVideoPlayer from './YouTubeVideoPlayer';
 import { PauseIcon, PlayIcon, SyncIcon } from './icons';
 
@@ -459,9 +460,7 @@ export default function VideoPlayerApp({
               </Transcript>
             )}
             {transcript instanceof Error && (
-              <div data-testid="transcript-error">
-                Unable to load transcript: {transcript.message}
-              </div>
+              <TranscriptError error={transcript} />
             )}
             <div
               id={bucketContainerId}

via/static/scripts/video_player/components/test/TranscriptError-test.js

@@ -0,0 +1,33 @@
+import { mount } from 'enzyme';
+
+import { APIError } from '../../utils/api';
+import TranscriptError from '../TranscriptError';
+
+describe('TranscriptError', () => {
+  it('displays just `Error.message` if there are no error details', () => {
+    const wrapper = mount(
+      <TranscriptError error={new Error('Something went wrong')} />
+    );
+    assert.equal(
+      wrapper.text(),
+      ['Unable to load transcript', 'Something went wrong'].join('')
+    );
+  });
+
+  it('displays `APIError.error.title` field if present', () => {
+    const error = new APIError(404, {
+      code: 'VideoNotFound',
+      title: 'The video was not found',
+      detail: 'Some long details here',
+    });
+    const wrapper = mount(<TranscriptError error={error} />);
+    assert.equal(
+      wrapper.text(),
+      [
+        'Unable to load transcript',
+        'The video was not found',
+        'Error details:Some long details here',
+      ].join('')
+    );
+  });
+});

via/static/scripts/video_player/components/test/VideoPlayerApp-test.js

@@ -195,15 +195,9 @@ describe('VideoPlayerApp', () => {
       fakeCallAPI.withArgs(videoPlayerConfig.api.transcript).rejects(error);
 
       const wrapper = createVideoPlayerUsingAPI();
-      const errorDisplay = await waitForElement(
-        wrapper,
-        '[data-testid="transcript-error"]'
-      );
+      const errorDisplay = await waitForElement(wrapper, 'TranscriptError');
 
-      assert.equal(
-        errorDisplay.text(),
-        `Unable to load transcript: ${error.message}`
-      );
+      assert.equal(errorDisplay.prop('error'), error);
     });
   });
 

via/static/scripts/video_player/utils/api.ts

@@ -10,22 +10,17 @@ export type APIMethod = {
   url: string;
 };
 
-export class APIError extends Error {
-  /** The HTTP status code of the response. */
+/**
+ * Structure of a JSON API error.
+ *
+ * See https://jsonapi.org/format/#error-objects.
+ */
+export type JSONAPIError = {
   status: number;
-
-  /**
-   * Payload of the response.
-   */
-  data: unknown;
-
-  constructor(status: number, data: unknown) {
-    super('API call failed');
-
-    this.status = status;
-    this.data = data;
-  }
-}
+  code: string;
+  title: string;
+  detail: string;
+};
 
 /**
  * Structure of a JSON API response.
@@ -37,9 +32,25 @@ export type JSONAPIObject<Properties extends object> = {
     type: string;
     id: string;
     attributes: Properties;
+    errors: JSONAPIError[];
   };
 };
 
+export class APIError extends Error {
+  /** The HTTP status code of the response. */
+  status: number;
+
+  /** Error details returned by the API. */
+  error: JSONAPIError | undefined;
+
+  constructor(status: number, error?: JSONAPIError) {
+    super('API call failed');
+
+    this.status = status;
+    this.error = error;
+  }
+}
+
 /**
  * Make an API call to the backend.
  *
@@ -57,7 +68,15 @@ export async function callAPI<T = unknown>(api: APIMethod): Promise<T> {
   const resultData = await result.json().catch(() => null);
 
   if (result.status >= 400 && result.status < 600) {
-    throw new APIError(result.status, resultData);
+    let error;
+    if (
+      resultData &&
+      Array.isArray(resultData.errors) &&
+      resultData.errors.length > 0
+    ) {
+      error = resultData.errors[0];
+    }
+    throw new APIError(result.status, error);
   }
 
   return resultData;

via/static/scripts/video_player/utils/test/api-test.js

@@ -33,38 +33,71 @@ describe('callAPI', () => {
     assert.deepEqual(result, transcriptsAPIResponse);
   });
 
-  it('throws exception if result is not JSON', async () => {
-    fakeFetch
-      .withArgs(videoPlayerConfig.api.transcript.url)
-      .resolves(new Response('<b>Oh no</b>', { status: 500 }));
-
-    let error;
-    try {
-      await callAPI(videoPlayerConfig.api.transcript);
-    } catch (e) {
-      error = e;
-    }
-
-    assert.instanceOf(error, APIError);
-    assert.equal(error.status, 500);
-    assert.equal(error.data, null);
-    assert.equal(error.message, 'API call failed');
-  });
+  context('when request fails', () => {
+    it('throws exception if result is not JSON', async () => {
+      fakeFetch
+        .withArgs(videoPlayerConfig.api.transcript.url)
+        .resolves(new Response('<b>Oh no</b>', { status: 500 }));
 
-  it('throws exception if API request fails', async () => {
-    fakeFetch
-      .withArgs(videoPlayerConfig.api.transcript.url)
-      .resolves(jsonResponse(404));
-
-    let error;
-    try {
-      await callAPI(videoPlayerConfig.api.transcript);
-    } catch (e) {
-      error = e;
-    }
-
-    assert.instanceOf(error, APIError);
-    assert.equal(error.status, 404);
-    assert.equal(error.message, 'API call failed');
+      let error;
+      try {
+        await callAPI(videoPlayerConfig.api.transcript);
+      } catch (e) {
+        error = e;
+      }
+
+      assert.instanceOf(error, APIError);
+      assert.equal(error.status, 500);
+      assert.isUndefined(error.error);
+      assert.equal(error.message, 'API call failed');
+    });
+
+    [{}, { errors: [] }].forEach(responseBody => {
+      it('throws exception without `error` if `errors` field is missing or empty', async () => {
+        fakeFetch
+          .withArgs(videoPlayerConfig.api.transcript.url)
+          .resolves(jsonResponse(404, responseBody));
+
+        let error;
+        try {
+          await callAPI(videoPlayerConfig.api.transcript);
+        } catch (e) {
+          error = e;
+        }
+
+        assert.instanceOf(error, APIError);
+        assert.isUndefined(error.error);
+        assert.equal(error.status, 404);
+        assert.equal(error.message, 'API call failed');
+      });
+    });
+
+    it('throws exception with `error` if `errors` field is present', async () => {
+      const responseBody = {
+        errors: [
+          {
+            code: 'VideoNotFound',
+            title: 'This video does not exist',
+            detail: 'Video ID is invalid',
+          },
+        ],
+      };
+
+      fakeFetch
+        .withArgs(videoPlayerConfig.api.transcript.url)
+        .resolves(jsonResponse(404, responseBody));
+
+      let error;
+      try {
+        await callAPI(videoPlayerConfig.api.transcript);
+      } catch (e) {
+        error = e;
+      }
+
+      assert.instanceOf(error, APIError);
+      assert.deepEqual(error.error, responseBody.errors[0]);
+      assert.equal(error.status, 404);
+      assert.equal(error.message, 'API call failed');
+    });
   });
 });