# 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.

```json
{ "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.

```json
{
  "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.

```bash
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/](/learn/errors/) for specific causes.
