YouTube Transcript API Error Codes

Reference normalized Scority API errors, HTTP statuses and recommended handling for transcript integrations.

View API reference Read rate limits

unauthorized

401

Missing, invalid or revoked API key.

Action: Send a valid x-api-key header from server-side code.

rate_limited

429

Short-window rate limit exceeded.

Action: Wait for Retry-After or reduce burst traffic.

quota_exceeded

429

Monthly product quota exhausted.

Action: Review usage and request a quota change if needed.

invalid_video_id

400

The video_id parameter is malformed.

Action: Send an 11-character YouTube video ID.

invalid_video_url

400

The video_url parameter is not a valid YouTube URL.

Action: Validate or normalize the URL before calling the API.

ambiguous_request

400

Both video_id and video_url were provided.

Action: Send exactly one video identifier.

invalid_language

400

The language or lang value is malformed.

Action: Use values such as en, en-US, ru or ru-RU.

ambiguous_language

400

Both language and lang were provided.

Action: Send only one language parameter.

transcript_not_available

404

Captions are not available for the requested video.

Action: Try another video or omit an unavailable language request.

upstream_transcript_failed

502

The upstream caption fetch failed.

Action: Retry later or contact support with the video ID.

transcript_fetch_failed

500

The transcript request failed unexpectedly.

Action: Retry and contact support if the error repeats.

rate_limit_unavailable

503

Rate limiting is unavailable in fail-closed mode.

Action: Retry later. This is an infrastructure protection state.

Code	Status	Meaning	Recommended action
unauthorized	401	Missing, invalid or revoked API key.	Send a valid x-api-key header from server-side code.
rate_limited	429	Short-window rate limit exceeded.	Wait for Retry-After or reduce burst traffic.
quota_exceeded	429	Monthly product quota exhausted.	Review usage and request a quota change if needed.
invalid_video_id	400	The video_id parameter is malformed.	Send an 11-character YouTube video ID.
invalid_video_url	400	The video_url parameter is not a valid YouTube URL.	Validate or normalize the URL before calling the API.
ambiguous_request	400	Both video_id and video_url were provided.	Send exactly one video identifier.
invalid_language	400	The language or lang value is malformed.	Use values such as en, en-US, ru or ru-RU.
ambiguous_language	400	Both language and lang were provided.	Send only one language parameter.
transcript_not_available	404	Captions are not available for the requested video.	Try another video or omit an unavailable language request.
upstream_transcript_failed	502	The upstream caption fetch failed.	Retry later or contact support with the video ID.
transcript_fetch_failed	500	The transcript request failed unexpectedly.	Retry and contact support if the error repeats.
rate_limit_unavailable	503	Rate limiting is unavailable in fail-closed mode.	Retry later. This is an infrastructure protection state.

Response shape

Errors are normalized

API errors use a stable JSON envelope so your integration can switch on error.code instead of parsing upstream text.

Do not expose raw upstream messages to end users.
Use Retry-After when present on 429 responses.
Treat transcript_not_available as a content availability result, not a system outage.
Treat repeated upstream_transcript_failed responses as candidates for support investigation.

Guides