Error Handling
Learn how to handle errors returned by the API.
Error Response Format
All errors are returned with a consistent JSON structure:
{
"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
{
"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
{
"error": "missing_api_key",
"message": "API key is required. Provide it via X-API-Key header or Authorization: Bearer token."
}{
"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
{
"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 |
Example Response
{
"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 | 200 |
Resolution
Wait for the rate limit window to reset (1 minute) before making more requests. Consider implementing exponential backoff in your application.
Example Response
{
"error": "rate_limited",
"message": "Rate limit exceeded. Please wait before making more requests."
}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
{
"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.