feat(storage): point a full trial account at the upgrade rather than at nothing

Being told "storage limit exceeded" when the limit is the free trial's three
gigabytes is a dead end. The account is not full because it stores a lot; it is
capped because it has not subscribed, and deleting files buys back very little.

The refusal now says which ceiling it is and carries its own error code, so the
toast can offer a link to the billing settings on the trial ceiling and stay
quiet on the paid one, where subscribing changes nothing.

The code had to survive the trip to the toast, which meant the upload helpers
throwing something that carries it rather than a bare Error. Two places were
dropping the server's message on the floor entirely: adding a version reported
"Failed to initialize upload" whatever the server said, and every asset upload
in the pane rewrote its own failure text.

components/video-page/assets-pane.tsx

@@ -3,6 +3,7 @@
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import * as tus from 'tus-js-client';
 import { toast } from 'sonner';
+import { toastApiError } from '@/lib/client/api-error';
 import {
   Download,
   FileVideo,
@@ -56,6 +57,7 @@ function formatTime(seconds: number): string {
 type UploadAudioResponse = {
   data?: { url?: string; reservationId?: string | null };
   error?: string;
+  code?: string;
 };
 
 function getAudioUploadValidationError(file: Blob): string | null {
@@ -369,10 +371,11 @@ export const AssetsPane = memo(function AssetsPane({
         const uploadPayload = (await uploadRes.json().catch(() => null)) as {
           data?: { url?: string; reservationId?: string | null };
           error?: string;
+          code?: string;
         } | null;
         const uploadedImageUrl = uploadPayload?.data?.url;
         if (!uploadRes.ok || !uploadedImageUrl) {
-          toast.error(`${file.name}: ${uploadPayload?.error || 'Failed to upload image'}`);
+          toastApiError(uploadPayload, 'Failed to upload image', { prefix: file.name });
           return false;
         }
 
@@ -385,7 +388,7 @@ export const AssetsPane = memo(function AssetsPane({
         return !!created;
       } catch (error) {
         console.error('Failed to upload image asset:', error);
-        toast.error(`${file.name}: Failed to upload image`);
+        toastApiError(error, 'Failed to upload image', { prefix: file.name });
         return false;
       }
     },
@@ -523,10 +526,11 @@ export const AssetsPane = memo(function AssetsPane({
             uploadToken: string;
           };
           error?: string;
+          code?: string;
         } | null;
 
         if (!initRes.ok || !initPayload?.data) {
-          toast.error(`${file.name}: ${initPayload?.error || 'Failed to initialize Bunny upload'}`);
+          toastApiError(initPayload, 'Failed to initialize Bunny upload', { prefix: file.name });
           return false;
         }
 
@@ -578,7 +582,7 @@ export const AssetsPane = memo(function AssetsPane({
         return true;
       } catch (error) {
         console.error('Failed to upload Bunny asset:', error);
-        toast.error(`${file.name}: Failed to upload Bunny video`);
+        toastApiError(error, 'Failed to upload Bunny video', { prefix: file.name });
         if (uploadedVideoId && uploadToken) {
           await fetch(`/api/videos/${videoId}/assets/bunny-init`, {
             method: 'DELETE',
@@ -631,7 +635,7 @@ export const AssetsPane = memo(function AssetsPane({
         return true;
       } catch (error) {
         console.error('Failed to upload R2 asset video:', error);
-        toast.error(`${file.name}: Failed to upload video`);
+        toastApiError(error, 'Failed to upload video', { prefix: file.name });
         return false;
       } finally {
         setIsUploadingBunny(false);
@@ -801,12 +805,12 @@ export const AssetsPane = memo(function AssetsPane({
         const uploadPayload = await readUploadAudioResponse(uploadRes);
         const uploadedUrl = uploadPayload?.data?.url;
         if (!uploadRes.ok || !uploadedUrl) {
-          toast.error(
-            `${fileName}: ${
-              uploadPayload?.error ||
-              (uploadRes.status === 413 ? MAX_AUDIO_UPLOAD_SIZE_MESSAGE : null) ||
-              'Failed to upload voice recording'
-            }`
+          toastApiError(
+            uploadPayload,
+            uploadRes.status === 413
+              ? MAX_AUDIO_UPLOAD_SIZE_MESSAGE
+              : 'Failed to upload voice recording',
+            { prefix: fileName }
           );
           return false;
         }
@@ -821,7 +825,7 @@ export const AssetsPane = memo(function AssetsPane({
         return !!created;
       } catch (error) {
         console.error('Failed to upload voice asset:', error);
-        toast.error(`${fileName}: Failed to upload voice recording`);
+        toastApiError(error, 'Failed to upload voice recording', { prefix: fileName });
         return false;
       }
     },

components/video-page/hooks/use-comment-actions.ts

@@ -28,6 +28,7 @@ import {
 } from '@/components/video-page/image-upload-utils';
 import { validateAnnotationStrokes } from '@/lib/validation';
 import { withWebmDuration } from '@/lib/webm-duration';
+import { ApiRequestError, apiRequestError, toastApiError } from '@/lib/client/api-error';
 
 interface UseCommentActionsParams extends CommentActionsConfig {
   setVideo: Dispatch<SetStateAction<VideoData | null>>;
@@ -61,17 +62,6 @@ function getAudioUploadFilename(blob: Blob): string {
   return 'recording.webm';
 }
 
-/**
- * A step of the submit that failed with something worth reading out.
- *
- * The attachment goes up before the comment does, so a full account fails on the
- * image and never reaches the comment at all. Reporting that as "failed to add
- * comment" tells the uploader to try again, which is the one thing that cannot
- * work. Carried as its own error type so a network fault, which has no message
- * anybody wants to see, still falls back to the generic line.
- */
-class CommentSubmitError extends Error {}
-
 export function useCommentActions({
   videoId,
   setVideo,
@@ -192,7 +182,7 @@ export function useCommentActions({
       } | null;
       const token = payload?.data?.token;
       if (!response.ok || !token) {
-        throw new Error(payload?.error || 'Failed to prepare upload');
+        throw apiRequestError(payload, 'Failed to prepare upload');
       }
       return token;
     },
@@ -274,10 +264,14 @@ export function useCommentActions({
           });
 
           if (!imageRes.ok) {
+            // The attachment goes up before the comment does, so a full account
+            // fails here and never reaches the comment at all. Thrown with the
+            // code attached so the catch below can offer the way out.
             const imagePayload = (await imageRes.json().catch(() => null)) as {
               error?: string;
+              code?: string;
             } | null;
-            throw new CommentSubmitError(imagePayload?.error || 'Failed to upload image');
+            throw apiRequestError(imagePayload, 'Failed to upload image');
           }
           const imageDataResponse = await imageRes.json();
           imageData = { url: imageDataResponse.data.url };
@@ -336,8 +330,11 @@ export function useCommentActions({
               ),
             };
           });
-          const payload = (await res.json().catch(() => null)) as { error?: string } | null;
-          toast.error(payload?.error || 'Failed to add comment');
+          const payload = (await res.json().catch(() => null)) as {
+            error?: string;
+            code?: string;
+          } | null;
+          toastApiError(payload, 'Failed to add comment');
         }
       } catch (error) {
         setVideo((prev) => {
@@ -351,7 +348,9 @@ export function useCommentActions({
             ),
           };
         });
-        toast.error(error instanceof CommentSubmitError ? error.message : 'Failed to add comment');
+        // A network fault has no message anybody wants to see, so only an
+        // ApiRequestError speaks for itself; toastApiError falls back for the rest.
+        toastApiError(error instanceof ApiRequestError ? error : null, 'Failed to add comment');
       } finally {
         setIsSubmittingComment(false);
         setIsUploadingImage(false);

components/video-page/hooks/use-version-actions.ts

@@ -12,6 +12,7 @@ import {
 import type { VersionActionsConfig, VideoData } from '@/components/video-page/types';
 import { resolvePublicBunnyCdnHostname } from '@/lib/bunny-cdn';
 import { cleanupPendingR2VideoUpload, uploadVideoToR2 } from '@/lib/client/r2-video-upload';
+import { apiRequestError, toastApiError } from '@/lib/client/api-error';
 
 /** What a failed version upload has to undo, depending on which provider it started on. */
 type PendingVersionCleanup =
@@ -113,7 +114,13 @@ export function useVersionActions({
       body: JSON.stringify({ title, sizeBytes: file.size.toString() }),
     });
 
-    if (!initRes.ok) throw new Error('Failed to initialize upload');
+    if (!initRes.ok) {
+      const initPayload = (await initRes.json().catch(() => null)) as {
+        error?: string;
+        code?: string;
+      } | null;
+      throw apiRequestError(initPayload, 'Failed to initialize upload');
+    }
     const {
       data: { videoId: bunnyVideoId, libraryId, signature, expirationTime, uploadToken },
     } = await initRes.json();
@@ -236,7 +243,7 @@ export function useVersionActions({
 
       if (!res.ok) {
         const data = await res.json().catch(() => null);
-        throw new Error(data?.error || 'Failed to create version');
+        throw apiRequestError(data, 'Failed to create version');
       }
 
       const versionData = await res.json();
@@ -277,7 +284,7 @@ export function useVersionActions({
         }
       }
       console.error('Failed to create version:', errorObj);
-      toast.error(errorObj.message || 'Failed to create version');
+      toastApiError(errorObj, 'Failed to create version');
     } finally {
       setIsCreatingVersion(false);
       setNewVersionUploadProgress(0);

components/video-page/hooks/use-video-assets.ts

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { toast } from 'sonner';
 import type { VideoAsset } from '@/components/video-page/types';
+import { apiRequestError, toastApiError } from '@/lib/client/api-error';
 
 type BunnyDownloadPreference = 'original' | 'compressed';
 
@@ -43,6 +44,7 @@ interface AssetsListResponse {
 interface AssetCreateResponse {
   data?: VideoAsset;
   error?: string;
+  code?: string;
 }
 
 const ASSET_PAGE_SIZE = 40;
@@ -185,7 +187,7 @@ export function useVideoAssets({
         });
         const body = (await res.json().catch(() => null)) as AssetCreateResponse | null;
         if (!res.ok || !body?.data) {
-          toast.error(body?.error || 'Failed to create asset');
+          toastApiError(body, 'Failed to create asset');
           return null;
         }
 
@@ -288,7 +290,7 @@ export function useVideoAssets({
       } | null;
       const token = payload?.data?.token;
       if (!response.ok || !token) {
-        throw new Error(payload?.error || 'Failed to prepare upload');
+        throw apiRequestError(payload, 'Failed to prepare upload');
       }
       return token;
     },