Ошибки

Сначала определите, где произошла ошибка. Если 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, internal_error и service_unavailable. Выдержите паузу из Retry-After, а если заголовка нет, увеличивайте интервал между попытками.
• Для повторного POST /v1/transcriptions сохраняйте прежний Idempotency-Key. Если первый запрос успел пройти, новая попытка не приведёт к повторному списанию.
• Остальные ошибки требуют исправления запроса. Отправлять его без изменений не стоит.

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

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

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