Error Handling
Learn how to handle errors returned by the API.
Error Response Format
All errors are returned with a consistent JSON structure, inside a detail object:
{
"detail": {
"error": "error_code",
"message": "A human-readable description of the error",
"video_id": "dQw4w9WgXcQ" // Optional, included when relevant
}
}HTTP Status Codes
The API uses standard HTTP status codes to indicate the success or failure of requests:
Bad Request
The request was malformed or contains invalid parameters.
Common Causes
- -Invalid video ID format (must be 11 characters)
- -Invalid channel ID format
- -Missing required parameters
- -Parameter values out of allowed range
Example Response
{
"detail": {
"error": "invalid_video_id",
"message": "Invalid video ID format: abc. Must be 11 characters.",
"video_id": "abc"
}
}Unauthorized
Authentication failed or API key is invalid.
Common Causes
- -Missing Authorization header
- -Invalid API key format
- -API key has been revoked
- -API key does not exist
Example Responses
{
"detail": {
"error": "missing_api_key",
"message": "API key is required. Provide it via X-API-Key header or Authorization: Bearer token."
}
}{
"detail": {
"error": "invalid_api_key",
"message": "Invalid or inactive API key."
}
}Payment Required
Your account has run out of credits.
Resolution
Top up your account balance from the Billing page to continue making API calls.
Example Response
{
"detail": {
"error": "insufficient_credits",
"message": "Insufficient credits. Please purchase more credits.",
"available": 0,
"required": 1
}
}Not Found
The requested resource was not found.
Error Codes
| Error Code | Description |
|---|---|
| video_not_found | Video does not exist or is private |
| channel_not_found | Channel does not exist |
| no_transcript_found | No transcript available for this video/language |
| transcripts_disabled | Transcripts are disabled for this video |
| comments_disabled | Comments are turned off for this video (comments endpoint) |
Example Response
{
"detail": {
"error": "video_not_found",
"message": "Video dQw4w9WgXcQ was not found or is unavailable",
"video_id": "dQw4w9WgXcQ"
}
}Too Many Requests
You have exceeded the rate limit.
Rate Limits
| Limit | Value |
|---|---|
| Requests per minute | 500 |
Resolution
Wait for the rate limit window to reset (1 minute) before making more requests. Consider implementing exponential backoff in your application.
Example Response
{
"detail": {
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 500 requests per minute.",
"retry_after": 42
}
}Retrying With No Credits
An API key that keeps retrying after 402 insufficient_credits (20 refusals within 10 minutes) gets 429 insufficient_credits_retry_later for a while: 60 seconds the first time, then 300, then 900. Every 429 carries a Retry-After header with the seconds to wait. Topping up from the Billing page lifts the pause within seconds. These responses cost no credits.
{
"detail": {
"error": "insufficient_credits_retry_later",
"message": "Your credits are exhausted, so retries from this API key are paused for 60 seconds. Top up at https://fetchtranscript.com/dashboard/billing: requests are accepted again within seconds of a top-up.",
"video_id": "dQw4w9WgXcQ",
"retry_after": 60
}
}Service Unavailable
The service is temporarily unavailable.
Common Causes
- -Temporary issues with YouTube's servers
- -High traffic causing temporary overload
- -Scheduled maintenance
Resolution
Retry your request after a short delay. We recommend implementing retry logic with exponential backoff.
Example Response
{
"detail": {
"error": "service_unavailable",
"message": "Unable to fetch transcript. Please try again later.",
"video_id": "dQw4w9WgXcQ"
}
}Error Handling Best Practices
1. Always check HTTP status codes
Check the HTTP status code before parsing the response body. Only 2xx responses contain successful data.
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
elif response.status_code == 401:
print("Invalid API key")
elif response.status_code == 404:
error = response.json()
print(f"Not found: {error['message']}")
elif response.status_code == 429:
print("Rate limited, waiting...")
time.sleep(60)
else:
print(f"Error: {response.status_code}")2. Implement retry logic with exponential backoff
For 429 and 503 errors, implement retries with increasing delays.
import time
def fetch_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response.json()
elif response.status_code in [429, 503]:
delay = (2 ** attempt) * 1 # 1s, 2s, 4s
time.sleep(delay)
else:
break
return None3. Log errors for debugging
Always log the full error response including the error code, message, and any additional fields. This makes debugging much easier.