СправочникОшибки

Ошибки

Все ошибки API используют единый формат — повторяйте запрос только при 5xx, никогда при 4xx.

Формат ответа

Любая ошибка HTTP возвращает JSON с полем error. Структура одинакова для всех эндпоинтов: type машиночитаемый, message для людей, request_id присутствует всегда.

error.jsonjson

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "url is required",
    "param": "url",
    "request_id": "req_01HZX5T9Y2R7Q8KMPF3VZABCDE"
  }
}

Типы

Поле type принимает одно из шести значений. HTTP-статус всегда соответствует типу — можно ветвиться по любому из них.

Тип	HTTP	Значение
`invalid_request_error`	400	Некорректное тело запроса, отсутствует обязательное поле или неверное значение enum.
`authentication_error`	401	Bearer-токен отсутствует, некорректен или отозван.
`permission_error`	403	У ключа нет нужного scope либо аккаунт заблокирован.
`not_found_error`	404	Запрошенного ресурса не существует.
`rate_limit_error`	429	Зарезервировано на будущее — пока не применяется.
`api_error`	500	Баг на нашей стороне. Обратитесь в поддержку и укажите request_id.

Частые коды

Поле code машиночитаемое и стабильное. Ветвитесь по code, а не по message.

missing_field — Не передано обязательное поле (см. param — какое именно).
invalid_value — Поле передано, но значение вне допустимого диапазона, формата или enum.
invalid_url — Переданный url не является корректным URL.
unsupported_source — Источник распознан, но не поддерживается (например, приватное видео).
invalid_api_key — Bearer-токен повреждён или не соответствует ни одному ключу.
key_revoked — Ключ отозван — выпустите новый в разделе Developers.
insufficient_points — На балансе недостаточно средств для запуска задачи. Пополните и повторите.
duration_too_long — Файл превышает лимит ~10 часов на файл. Разделите и отправьте по частям.
transcription_failed — Ошибка на стадии обработки. Появляется в объекте Transcription, а не в ответе на создание.
internal_error — Необработанная ошибка сервера. Можно повторить с backoff; если повторяется — в поддержку.

Request ID

В каждом ответе — и успешном, и с ошибкой — есть request_id: в теле ошибки и в заголовке X-Request-Id. Всегда прикладывайте его при обращении в поддержку: по нему мы мгновенно находим полный трейс.

Повторы

Повторяйте только при 5xx. Используйте экспоненциальный backoff, начиная с 1 с (1 с, 2 с, 4 с, 8 с, ограничение 30 с) с jitter. Никогда не повторяйте 4xx автоматически — запрос упадёт так же. При 429 соблюдайте заголовок Retry-After, если он есть; иначе ждите минимум 1 с.

Ошибки на уровне транскрипции

Асинхронные сбои не возвращаются как HTTP-ошибка в ответе на создание — там будет 200 с ID задачи. Итоговое состояние приходит как status: "failed" с полем error в объекте Transcription. Обрабатывайте их через polling или вебхук transcription.failed.

transcription.jsonjson

{
  "id": "trs_01HZX5T9Y2R7Q8KMPF3VZABCDE",
  "status": "failed",
  "error": {
    "code": "transcription_failed",
    "message": "Upstream transcription provider returned an error after 3 attempts."
  }
}

← Назад

Вебхуки

API Reference