sample: surface YouTube datacenter-IP block as a friendly notice

Vercel functions hit YouTube's bot challenge because Vercel runs on AWS
Lambda — datacenter IPs are gated regardless of client choice. In v1.10.0
the library throws an informative error in this case (rather than the
silent empty-array of older versions), which surfaced on the deployed
demo as a generic 500. This commit improves the demo's failure mode:

- New shared handleApiError() helper detects the bot-challenge family of
  errors (LOGIN_REQUIRED, "not a bot", "no longer supported", "Video not
  playable on any client") and returns a structured 503 response with
  { code: 'youtube_blocked_datacenter_ip', message, debug }.
- Real failures (network errors, etc.) still return 500 with code:
  'unknown_error' so they remain distinguishable.
- Both API routes (subtitles, videoDetails) now use the shared helper.
- Frontend reads the response body for { code, message } instead of just
  the HTTP status, and renders the datacenter-IP case as a calm amber
  notice ("Live demo limitation") with explainer links to the README,
  instead of treating it as a bug.
- Real errors keep the existing inline red-bordered treatment.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: devhims

sample/app/api/_lib/handleError.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+
+/**
+ * Maps library errors to HTTP responses. YouTube blocks datacenter IPs
+ * (Vercel, AWS Lambda, Cloudflare Workers) with a bot challenge — the
+ * library will throw a descriptive "Video not playable on any client"
+ * error in that case. We surface that as a 503 with a friendly explanation
+ * instead of a generic 500.
+ */
+export function handleApiError(error: unknown): NextResponse {
+  const message = error instanceof Error ? error.message : String(error);
+
+  const looksLikeBotChallenge =
+    message.includes('LOGIN_REQUIRED') ||
+    message.includes('not a bot') ||
+    message.includes('no longer supported') ||
+    message.includes('Video not playable on any client');
+
+  if (looksLikeBotChallenge) {
+    return NextResponse.json(
+      {
+        code: 'youtube_blocked_datacenter_ip',
+        message:
+          'YouTube is blocking this server. Most cloud hosts (Vercel, AWS Lambda, Cloudflare Workers) share IP ranges that YouTube gates with a bot challenge — no client-side fix can bypass it. The library works on residential IPs: run the demo locally to see it in action, or wire up a residential proxy via the `fetch` option.',
+        debug: message,
+      },
+      { status: 503 }
+    );
+  }
+
+  return NextResponse.json(
+    { code: 'unknown_error', message },
+    { status: 500 }
+  );
+}

sample/app/api/subtitles/route.ts

@@ -1,23 +1,23 @@
 import { getSubtitles } from 'youtube-caption-extractor';
-import { NextResponse } from 'next/server';
-import { type NextRequest } from 'next/server';
+import { NextResponse, type NextRequest } from 'next/server';
+import { handleApiError } from '../_lib/handleError';
 
 export async function GET(request: NextRequest) {
   const searchParams = request.nextUrl.searchParams;
   const videoID = searchParams.get('videoID');
   const lang = searchParams.get('lang') || 'en';
 
   if (!videoID) {
-    return NextResponse.json({ error: 'Missing videoID' }, { status: 400 });
+    return NextResponse.json(
+      { code: 'missing_video_id', message: 'Missing videoID' },
+      { status: 400 }
+    );
   }
 
   try {
     const subtitles = await getSubtitles({ videoID, lang });
     return NextResponse.json({ subtitles }, { status: 200 });
   } catch (error) {
-    return NextResponse.json(
-      { error: (error as Error).message },
-      { status: 500 }
-    );
+    return handleApiError(error);
   }
 }

sample/app/api/videoDetails/route.ts

@@ -1,23 +1,23 @@
 import { getVideoDetails } from 'youtube-caption-extractor';
-import { NextResponse } from 'next/server';
-import { type NextRequest } from 'next/server';
+import { NextResponse, type NextRequest } from 'next/server';
+import { handleApiError } from '../_lib/handleError';
 
 export async function GET(request: NextRequest) {
   const searchParams = request.nextUrl.searchParams;
   const videoID = searchParams.get('videoID');
   const lang = searchParams.get('lang') || 'en';
 
   if (!videoID) {
-    return NextResponse.json({ error: 'Missing videoID' }, { status: 400 });
+    return NextResponse.json(
+      { code: 'missing_video_id', message: 'Missing videoID' },
+      { status: 400 }
+    );
   }
 
   try {
     const videoDetails = await getVideoDetails({ videoID, lang });
     return NextResponse.json({ videoDetails }, { status: 200 });
   } catch (error) {
-    return NextResponse.json(
-      { error: (error as Error).message },
-      { status: 500 }
-    );
+    return handleApiError(error);
   }
 }

sample/app/page.tsx

@@ -4,6 +4,19 @@ import { useEffect, useMemo, useRef, useState } from 'react';
 
 type Subtitle = { start: string; dur: string; text: string };
 type VideoDetails = { title?: string; description?: string };
+type ErrorState = { message: string; code?: string };
+
+async function readApiError(res: Response): Promise<ErrorState> {
+  try {
+    const body = await res.json();
+    return {
+      message: body.message ?? body.error ?? `HTTP ${res.status}`,
+      code: body.code,
+    };
+  } catch {
+    return { message: `HTTP ${res.status}` };
+  }
+}
 
 const YOUTUBE_ID_REGEX =
   /(?:youtube\.com\/(?:[^/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/|youtube\.com\/shorts\/)([A-Za-z0-9_-]{11})/;
@@ -81,7 +94,7 @@ export default function HomePage() {
   const [subtitles, setSubtitles] = useState<Subtitle[]>([]);
   const [videoDetails, setVideoDetails] = useState<VideoDetails>({});
   const [videoId, setVideoId] = useState('');
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState<ErrorState | null>(null);
   const [isFetching, setIsFetching] = useState(false);
   const [query, setQuery] = useState('');
   const [copied, setCopied] = useState(false);
@@ -127,7 +140,9 @@ export default function HomePage() {
     const raw = overrideInput ?? input;
     const id = extractVideoId(raw);
     if (!id || id.length !== 11) {
-      setError('That doesn’t look like a YouTube URL or video ID.');
+      setError({
+        message: 'That doesn’t look like a YouTube URL or video ID.',
+      });
       return;
     }
     if (overrideInput) setInput(overrideInput);
@@ -139,22 +154,33 @@ export default function HomePage() {
         fetch(`/api/subtitles?videoID=${id}&lang=${lang}`),
         fetch(`/api/videoDetails?videoID=${id}&lang=${lang}`),
       ]);
-      if (!subsRes.ok) throw new Error(`Subtitles API: HTTP ${subsRes.status}`);
-      if (!detailsRes.ok)
-        throw new Error(`Details API: HTTP ${detailsRes.status}`);
+      if (!subsRes.ok) {
+        setError(await readApiError(subsRes));
+        setSubtitles([]);
+        setVideoDetails({});
+        return;
+      }
+      if (!detailsRes.ok) {
+        setError(await readApiError(detailsRes));
+        setSubtitles([]);
+        setVideoDetails({});
+        return;
+      }
       const subsData = await subsRes.json();
       const detailsData = await detailsRes.json();
       const subs: Subtitle[] = subsData.subtitles ?? [];
       setSubtitles(subs);
       setVideoDetails(detailsData.videoDetails ?? {});
       setVideoId(id);
       if (subs.length === 0) {
-        setError(
-          `No captions for ${LANGUAGES.find((l) => l[0] === lang)?.[1] ?? lang}. This video might not be subtitled in that language.`
-        );
+        setError({
+          message: `No captions for ${LANGUAGES.find((l) => l[0] === lang)?.[1] ?? lang}. This video might not be subtitled in that language.`,
+        });
       }
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Unknown error');
+      setError({
+        message: err instanceof Error ? err.message : 'Unknown error',
+      });
       setSubtitles([]);
       setVideoDetails({});
     } finally {
@@ -286,11 +312,40 @@ export default function HomePage() {
           </div>
         </form>
 
-        {/* Error */}
+        {/* Error / notice */}
         {error && (
-          <p className='mt-6 text-sm text-stone-600 border-l-2 border-stone-300 pl-3'>
-            {error}
-          </p>
+          error.code === 'youtube_blocked_datacenter_ip' ? (
+            <aside className='mt-8 rounded-md border border-amber-200 bg-amber-50/60 px-5 py-4'>
+              <div className='font-mono text-[10px] uppercase tracking-[0.22em] text-amber-700 mb-2'>
+                Live demo limitation
+              </div>
+              <p className='text-sm text-stone-700 leading-relaxed'>
+                {error.message}
+              </p>
+              <div className='mt-3 flex flex-wrap gap-x-5 gap-y-1 text-xs'>
+                <a
+                  href='https://github.com/devhims/youtube-caption-extractor#deployment-environments'
+                  target='_blank'
+                  rel='noopener noreferrer'
+                  className='text-amber-800 hover:text-amber-900 underline decoration-amber-300 hover:decoration-amber-700 decoration-1 underline-offset-[3px] transition-colors'
+                >
+                  why this happens
+                </a>
+                <a
+                  href='https://github.com/devhims/youtube-caption-extractor'
+                  target='_blank'
+                  rel='noopener noreferrer'
+                  className='text-amber-800 hover:text-amber-900 underline decoration-amber-300 hover:decoration-amber-700 decoration-1 underline-offset-[3px] transition-colors'
+                >
+                  run locally
+                </a>
+              </div>
+            </aside>
+          ) : (
+            <p className='mt-6 text-sm text-stone-600 border-l-2 border-stone-300 pl-3'>
+              {error.message}
+            </p>
+          )
         )}
 
         {/* Loading */}

sample/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.