# Ошибки

> Разберитесь в кодах ошибок API и транскрибации. Узнайте, когда исправить запрос, а когда повторить попытку.

Canonical: https://transcript1.com/ru/docs/errors
Language: ru
Last updated: 2026-10-19

Сначала определите, где произошла ошибка. Если API не принял запрос, вы получите HTTP-ошибку. Если запрос прошёл, но расшифровать запись не удалось, у созданной задачи будет `status=failed`.

## Формат ошибки

Для всех ошибок запросов к `/v1` API использует один формат:

```json
{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}
```

Логику обработки привязывайте к `code`, а `message` показывайте пользователю. На текст сообщения полагаться нельзя: мы можем его изменить. Значение `retryable=true` означает, что повторный запрос позже может пройти.

В зависимости от ошибки рядом с `retryable` могут быть дополнительные поля:

| Поле | Код ошибки | Что содержит |
|---|---|---|
| `action_url` | `insufficient_minutes` | Ссылку для подключения тарифа или покупки минут. |
| `minutes_needed`, `minutes_remaining` | `insufficient_minutes` | Сколько минут требуется и сколько осталось. Если длительность ещё неизвестна, в первом поле будет `null`. |
| `supported_platforms` | `unsupported_platform` | Список допустимых платформ: `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`. |
| `missing_chunks` | `upload_incomplete` | Индексы недостающих частей файла. |
| `max_bytes` | `media_too_large` | Ваш лимит размера файла в байтах. |
| `params` | `invalid_request` | Ошибки в полях тела запроса или query-параметрах. Ключ объекта — имя поля, значение — описание проблемы. |

## Ошибки запроса

| HTTP-код | `code` | Повторить без изменений? | Причина и действие |
|---|---|---|---|
| 400, 422 | `invalid_request` | Нет | Не хватает параметра или поля, либо значение недопустимо. Например, нельзя сочетать `diarize` с `source: "captions"`, а `reuse_recent` — с `webhook_url`. Невалидный JSON даёт тот же код. |
| 422 | `invalid_url` | Нет | Проверьте ссылку и её соответствие `platform`. Подойдут YouTube, X, TikTok, Instagram, Facebook, Bluesky и другие платформы из раздела [«Источники и параметры»](https://transcript1.com/ru/docs/sources-and-options). |
| 422 | `unsupported_platform` | Нет | API не поддерживает указанное значение `platform`. |
| 422 | `unsupported_media` | Нет | Расширение загруженного файла не входит в список поддерживаемых. |
| 401 | `unauthorized` | Нет | Ключ или токен не передан, неверен, истёк или отозван. Для загрузки — токен неверен или истёк. |
| 403 | `insufficient_scope` | Нет | В OAuth-токене нет нужного разрешения: `transcriptions:read` или `transcriptions:write`. |
| 403 | `email_not_verified` | Нет | Для создания задачи сначала подтвердите почту. |
| 402 | `insufficient_minutes` | Нет | На балансе 0 минут или их не хватает на запись. |
| 402 | `no_active_plan` | Нет | Для покупки дополнительных минут нужен активный платный тариф. Ошибку возвращает только платёжный эндпоинт личного кабинета, не эндпоинты транскрибации. |
| 404 | `not_found` | Нет | Задача не найдена или принадлежит другой команде. |
| 409 | `upload_incomplete` | Нет | Загрузите недостающие части файла и снова вызовите завершение загрузки. |
| 409 | `invalid_state` | Нет | Задача больше не ждёт загрузки. Отправлять части или завершать её уже нельзя. |
| 409 | `idempotency_conflict` | Нет | Этот `Idempotency-Key` ранее передали с другим набором параметров. |
| 413 | `media_too_large` | Нет | Размер файла превышает ваш лимит — см. [«Загрузка файлов»](https://transcript1.com/ru/docs/uploads). |
| 413 | `invalid_request` | Нет | Тело JSON превышает 1 МБ. Для слишком большого файла используется другой код: `media_too_large`. |
| 429 | `rate_limited` | Да | Исчерпан лимит запросов в минуту. Число секунд до повтора указано в `Retry-After`. |
| 429 | `too_many_active_jobs` | Да | Достигнут лимит выполняющихся задач или открытых загрузок. Подождите столько секунд, сколько указано в `Retry-After`. |
| 500 | `internal_error` | Да | Ошибка на стороне transcript1. Попробуйте ещё раз чуть позже. |
| 503 | `service_unavailable` | Да | Сервис временно недоступен. Попробуйте ещё раз чуть позже. |

Для браузерных запросов с cookie входа вместо Bearer-аутентификации проверяем также источник запроса. Вызов с другого сайта вернёт `403 forbidden_origin`. К API-запросам с заголовком `Authorization` эта проверка не относится.

В любом ответе `429` есть `Retry-After` — время ожидания в секундах. Значения лимитов приведены в разделе [«Тарифы и лимиты»](https://transcript1.com/ru/docs/billing-and-limits).

## Когда повторять запрос

- Автоматически повторяйте запрос только при `retryable=true`. Это ошибки `rate_limited`, `too_many_active_jobs`, `internal_error` и `service_unavailable`. Выдержите паузу из `Retry-After`, а если заголовка нет, увеличивайте интервал между попытками.
- Для повторного `POST /v1/transcriptions` сохраняйте прежний `Idempotency-Key`. Если первый запрос успел пройти, новая попытка не приведёт к повторному списанию.
- Остальные ошибки требуют исправления запроса. Отправлять его без изменений не стоит.

## Если транскрибация завершилась с ошибкой

Задача со `status=failed` содержит `error: { "code", "message" }`. HTTP-запрос к этому моменту мог давно завершиться успешно. Поэтому проверяйте `error`, когда запрашиваете статус или получаете [вебхук](https://transcript1.com/ru/docs/webhooks) `transcription.failed`.

| `error.code` | Что случилось | Что делать |
|---|---|---|
| `media_unavailable` | Видео удалено, не существует или недоступно. | Проверьте URL. Повтор без изменений не поможет. |
| `media_private` | Доступ к видео закрыт. | Нужен публичный пост. Для YouTube подойдёт также видео с доступом по ссылке. |
| `login_required` | Для просмотра нужен вход в аккаунт. | Не повторяйте: это постоянная ошибка, автоматических повторов нет. |
| `no_audio` | У видео нет звуковой дорожки. | Не повторяйте: это постоянная ошибка, автоматических повторов нет. |
| `age_restricted` | Просмотр ограничен по возрасту. | Вместо повторного запроса загрузите файл. |
| `live_stream` | Трансляция ещё идёт или не началась. | Попробуйте после её завершения. |
| `no_captions` | В режиме `captions` не нашлось подходящей дорожки субтитров. | Смените `source` на `"auto"` или `"stt"`. |
| `media_too_long` | Запись длиннее 5 часов — лимита распознавания речи. | Разделите запись. Повтор целиком не поможет. |
| `unsupported_media` | Не удалось прочитать файл или в нём нет аудиодорожки. | Отправьте файл в поддерживаемом формате. |
| `no_speech` | Речь не обнаружена. | Не повторяйте. |
| `unsupported_language` | Язык записи не поддерживается. | Укажите в `language` поддерживаемый код или `"auto"`. Без изменений не повторяйте. |
| `insufficient_minutes` | К моменту списания на балансе не хватило минут. | Пополните баланс и попробуйте снова. |
| `fetch_failed` | Несколько попыток скачать запись не удались. | Попробуйте ещё раз позже. |
| `transcription_failed` | Распознать речь не удалось даже после повторных попыток. | Попробуйте ещё раз позже. |

Если транскрибация завершилась с ошибкой или вы её отменили, платить не нужно. Уже списанные минуты вернём на баланс.