YouTube API Errors

Troubleshoot common YouTube API and transcript API errors, including invalid_video_id, unauthorized, rate_limited and upstream failures.

Read error reference View API docs

Direct answer

Start with the HTTP status and error.code

For Scority transcript requests, the useful field is error.code. It tells you whether to fix input, authenticate, slow down, check quota, try another video or retry later.

Do not parse raw upstream messages.
Do not retry malformed input.
Respect Retry-After for rate_limited responses.
Treat transcript_not_available as a content availability result.

Why errors happen

Why YouTube API errors happen

YouTube-related APIs sit between your app, credential rules, video availability, caption availability and upstream network behavior. A visible YouTube page does not guarantee that transcript text is available through an API.

The request can be malformed.
The key can be missing, invalid or revoked.
The video may not have accessible captions.
The upstream caption path can fail temporarily.
Your integration can exceed a rate limit or monthly quota.

Status	What to do	Relevant codes
400	Fix request input before retrying.	invalid_video_id, invalid_video_url, ambiguous_request, invalid_language, ambiguous_language
401	Send a valid x-api-key header from server-side code.	unauthorized
403	For Scority's public web proxy, /api/transcript returns 403 transcript_demo_disabled. Use https://api.scority.ai instead.	transcript_demo_disabled on the web app
429	Slow down or check monthly quota, depending on the error code.	rate_limited, quota_exceeded
404	The requested transcript was not available for that video or language.	transcript_not_available
502	Upstream transcript access failed and may be worth retrying later.	upstream_transcript_failed

400

400 errors

400-level validation errors usually mean the request should be corrected before retrying.

invalid_video_id: send an 11-character YouTube video ID.
invalid_video_url: send a valid YouTube URL.
ambiguous_request: send video_id or video_url, not both.
invalid_language: use a simple language value such as en or en-US.
ambiguous_language: send language or lang, not both.

401

401 unauthorized

unauthorized means the API key is missing, invalid or revoked.

Check that x-api-key is present.
Check that the request is going to https://api.scority.ai.
Check that the key was not exposed and rotated.
Keep the key server-side.

403

403 forbidden

The public web app route /api/transcript is intentionally disabled and returns transcript_demo_disabled. Production transcript requests should call https://api.scority.ai/v1/youtube/transcript with x-api-key.

429

429 rate limited

A 429 can mean rate_limited or quota_exceeded. They have different fixes.

rate_limited: slow down and respect Retry-After when present.
quota_exceeded: monthly quota is exhausted; reduce usage or request a quota change.
Do not retry either case in a tight loop.

Transcript failures

transcript_not_available and upstream_transcript_failed

These errors describe transcript availability and upstream fetch behavior, not necessarily a bug in your code.

transcript_not_available: captions were not available for that video or request.
upstream_transcript_failed: Scority could not fetch the upstream transcript path at that time.
Try another known-good video when debugging integration code.
Contact support with the video ID if a repeated upstream failure matters to your workflow.

Retries