Bug Report: GET /v1/youtube/transcript returns 206 (Transcript Unavailable) when lang parameter is omitted, even when captions exist

Bug Report: GET /v1/youtube/transcript returns 206 (Transcript Unavailable) when lang parameter is omitted, even when captions exist

Severity: High — causes false negatives for videos with non-English captions

Description

When calling GET /v1/youtube/transcript without the lang query parameter, the API returns HTTP 206 with {"error": "transcript-unavailable"} for videos that do have captions available (e.g., Portuguese auto-generated captions).

However, when the same request includes any lang parameter (even a language that doesn't match the video's captions), the API correctly falls back to the first available language and returns HTTP 200 with the full transcript.

Steps to Reproduce

Video: mkn_Bx-qe4o (has Portuguese auto-generated captions, visible in the YouTube player)

Request 1 — WITHOUT lang (fails): curl -s -w "\nHTTP: %{http_code}"
"https://api.supadata.ai/v1/youtube/transcript?videoId=mkn_Bx-qe4o&text=true"
-H "x-api-key: YOUR_KEY"

Response: HTTP: 206 {"error":"transcript-unavailable","message":"Transcript Unavailable","details":"No transcript is available for this video","documentationUrl":"https://docs.supadata.ai/errors/transcript-unavailable"}

Request 2 — WITH lang=pt (succeeds): curl -s -w "\nHTTP: %{http_code}"
"https://api.supadata.ai/v1/youtube/transcript?videoId=mkn_Bx-qe4o&text=true&lang=pt"
-H "x-api-key: YOUR_KEY"

Response: HTTP: 200 {"lang":"pt","availableLangs":["pt"],"content":"[música] Boa noite, seja novamente muito bem-vindo ao dia 2 do nosso seminário..."}

Request 3 — WITH lang=en (also succeeds — falls back to PT): curl -s -w "\nHTTP: %{http_code}"
"https://api.supadata.ai/v1/youtube/transcript?videoId=mkn_Bx-qe4o&text=true&lang=en"
-H "x-api-key: YOUR_KEY"

Response: HTTP: 200 {"lang":"pt","availableLangs":["pt"],"content":"[música] Boa noite, seja novamente muito bem-vindo ao dia 2 do nosso seminário..."}

Expected Behavior

When lang is omitted, the API should behave the same as when lang is provided with a non-matching language: fall back to the first available transcript language and return HTTP 200 with the content.

Per your own documentation: "If the video does not have a transcript in the preferred language, the endpoint will return a transcript in the first available language and a list of other available languages." This fallback should also apply when no lang preference is specified at all.

Actual Behavior

When lang is omitted, the API returns 206 with transcript-unavailable instead of falling back. This only happens when there is no "default" language transcript (likely English). Videos with only non-English captions (e.g., Portuguese, Spanish) are affected.

Impact

This bug causes all videos with only non-English captions to appear as having no transcripts available, even though captions are clearly present in the YouTube player. The workaround is to always include a lang parameter, which triggers the correct fallback behavior.

Environment

• Plan: Free (but the behavior is API logic, not plan-related)

• Date tested: March 20, 2026

• Endpoint: GET /v1/youtube/transcript