Reference
Errors and retries
Every YouTube Translate error code, what causes it, and whether retrying is safe.
Errors return a JSON body with a message and, for processing endpoints, a machine-readable code.
{ "error": { "message": "Insufficient credits", "code": "insufficient_credits" } }
Retry guidance
The most important column here is the last one. Retrying a non-retryable error just burns time and quota.
| Code | HTTP | Meaning | Retry? |
|---|---|---|---|
account_required |
403 | No account-owned credential was sent | No, fix the credential |
invalid_url |
400 | Not a usable public YouTube URL | No |
invalid_parameters |
400 | Bad language code, length, or format | No |
video_not_found |
404 | The video ID is unknown to the service | No |
source_missing |
409 | Retained source is gone; cannot reuse it | Sometimes, after re-transcribing |
budget_required |
428 | Uncached work needs max_credit_units |
Yes, after approval |
insufficient_credits |
402 | Balance too low for this request | Yes, after topping up |
idempotency_conflict |
409 | Same Idempotency-Key, different payload |
No, use a new key |
job_not_found |
404 | Unknown job ID | No |
processing_unavailable |
503 | The request could not be scheduled safely | Yes, with backoff |
mapping_unavailable |
503 | Internal video mapping is unavailable | Yes, with backoff |
unsupported |
400 | Operation is not offered | No |
The three errors you will actually hit
budget_required (428)
You asked for uncached work without a budget. This is a guard, not a bug: it stops an agent from spending silently.
{
"error": { "message": "Explicit credit budget required before uncached processing", "code": "budget_required" },
"quote": { "maximumCreditUnits": 300000, "cached": false }
}
Resolve it by quoting first, getting approval, then resending with max_credit_units at or above the quoted maximum.
insufficient_credits (402)
The balance cannot cover the maximum hold. Top up, or use a cached video instead. Note that cached reads also need credit, so a zero balance blocks everything except the demo.
idempotency_conflict (409)
The same Idempotency-Key was reused with a different body. Keys are scoped to a request's content. Use a fresh key for a genuinely different request.
Safe retry pattern
Retry only 503 and, after topping up, 402. Use exponential backoff and always send the same Idempotency-Key on the retry of a spending call, so a network blip cannot charge twice.
for attempt in 1 2 3 4; do
code=$(curl -s -o /tmp/out.json -w '%{http_code}' -X POST \
https://api.youtubetranslate.com/api/videos \
-H "X-API-Key: $YTT_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: stable-key-001' \
-d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","max_credit_units":300000}')
[ "$code" = "202" ] || [ "$code" = "200" ] && break
[ "$code" = "503" ] || break
sleep $((2 ** attempt))
done
Source problems are not service problems
A missing caption track, a bot check, or a private video is reported by the source, not by this service. Public audio transcription often succeeds where captions do not exist, but it can never reach a private, members-only, or age-restricted video. Those cases are refused rather than worked around.
See the troubleshooting guides under /learn/errors/ for specific causes.