Error codes
Every non-2xx response is JSON with an error envelope, and is never billed — you pay only for HTTP 200.
Envelope
{
"error": {
"code": "transcript_not_available",
"message": "This video has no captions or auto-generated subtitles."
}
}
Codes
| Code | HTTP | Meaning |
|---|---|---|
| invalid_video_id | 400 | videoId is missing or not 11 characters. |
| unauthorized | 401 | API key missing, invalid, or revoked. |
| insufficient_credits | 402 | Balance below the call cost. Top up or upgrade. |
| video_private | 403 | The video is private. |
| video_not_found | 404 | The video does not exist or was removed. |
| video_unavailable | 410 | The video is unavailable in the requested context. |
| transcript_not_available | 422 | No captions or auto-generated subtitles for this video, or the requested language has no track. |
| rate_limited | 429 | Plan rate limit hit. See x-ratelimit-reset. |
| upstream_error | 502 | Upstream fetch failed. Safe to retry; never billed. |
| timeout | 504 | Upstream fetch timed out. Safe to retry; never billed. |