Ошибки

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

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

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

{
  "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 могут быть дополнительные поля:

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

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

В любом ответе 429 есть Retry-After — время ожидания в секундах. Значения лимитов приведены в разделе «Тарифы и лимиты».

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

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

Расшифровка в реальном времени

POST /v1/live/sessions и остальные эндпоинты live используют тот же формат ошибки. К ним применимы также invalid_request, unsupported_language, insufficient_minutes и email_not_verified, а вместе с ними — live-коды из таблицы выше. Создание сессии не идемпотентно, поэтому повтор после too_many_live_sessions или live_capacity создаст новую сессию.

После создания сессии проблемы приходят по WebSocket как события error и коды закрытия, а не как HTTP-ошибки. Все события описаны в разделе «Расшифровка в реальном времени».

Live-сессия, которая завершилась по причине вроде balance_exhausted или idle_timeout, ошибкой не считается: она отправляет session.ended с причиной завершения и сохраняется. См. «Причины завершения».

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

Задача со status=failed содержит error: { "code", "message" }. HTTP-запрос к этому моменту мог давно завершиться успешно. Поэтому проверяйте error, когда запрашиваете статус или получаете вебхук transcription.failed. Если перевод не удался, отправляется вебхук transcription.translation.failed, а сама транскрипция из-за этого никогда не завершается ошибкой.

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