← All guides

IpBlocked and RequestBlocked: what to check next

Written by the VidWords Team · · Updated · Report a correction

These errors describe a refused request, not a missing transcript. They can appear when an automated lookup fails even though the same video plays in a browser. First check the video itself, then decide how your application should handle retrieval failures.

Separate availability from a request failure

Choose an appropriate next step

For a one-off task, reading or copying the transcript from YouTube may be enough. For an application, decide whether maintaining retrieval is part of your product or whether a hosted API fits the task. Neither approach guarantees access to every video.

A hosted API example

Set VIDWORDS_TOKEN in your environment, then request the videos you need. This example uses Python’s standard library:

import json, os, urllib.request

def get_transcripts(video_ids, language=None):
    payload = {"ids": video_ids}
    if language:
        payload["lang"] = language
    request = urllib.request.Request(
        "https://vidwords.com/api/transcripts",
        data=json.dumps(payload).encode(),
        headers={"Authorization": "Basic " + os.environ["VIDWORDS_TOKEN"],
                 "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(request, timeout=120) as response:
        return json.load(response)["results"]

for result in get_transcripts(["dQw4w9WgXcQ"]):
    if "error" in result:
        print(result["id"], result["error"])
    else:
        print(result["text"])

Limits and failed lookups

The REST API accepts up to 50 video ids per call. A delivered caption transcript uses one Cloud Request. A free account includes 100 one-time Developer Requests; see current plans and top-ups for continued use. Audio transcription requires separate AI Units and explicit consent through the API’s allowAsr option.

Read each result’s error field: one unavailable video does not make the rest of a batch fail. A lookup that returns no transcript is not charged. Hosted retrieval can still be refused by YouTube; it does not promise access to private, restricted or unavailable videos. See the API reference for response fields and limits.

Read the API docs →