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.