Обработка ошибок

Все ошибки API возвращают JSON-объект с полем error.

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

{
  "error": "человекочитаемое описание ошибки"
}

HTTP-коды статуса

Код	Значение
400	Некорректный запрос — проверьте тело запроса
401	Не авторизован — некорректные или отсутствующие учётные данные
402	Требуется оплата — закончились минуты транскрипции
404	Не найдено — ресурс не существует
409	Конфликт — конфликт состояния ресурса
429	Слишком много запросов — превышен лимит
500	Внутренняя ошибка сервера — попробуйте позже

Частые ошибки

Аутентификация

Ошибка	Код	Решение
missing Authorization header	401	Добавьте заголовок Authorization: Bearer <ключ>
invalid api key	401	Проверьте корректность ключа
api key has been revoked	401	Создайте новый ключ
token expired	401	Обновите JWT-токен

Транскрипция

Ошибка	Код	Решение
no transcription credits left	402	Купите пакет минут
file duration exceeds allowed limit for your plan	400	Используйте файл меньшей длительности
only one transcription can be in progress at a time	429	Дождитесь завершения текущего задания
daily usage limit exceeded	429	Подождите до следующего дня или обновите план
transcription not found	404	Проверьте ID транскрипции

Синтез речи (TTS)

Ошибка	Код	Решение
input text exceeds maximum length	400	Текст не должен превышать 5 000 символов
invalid voice	400	Используйте поддерживаемое имя голоса
tts job not found	404	Проверьте ID задания

Стратегия повторов

Для ошибок 429 и 5xx используйте экспоненциальную задержку:

import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429 or response.status_code >= 500:
            wait = 2 ** attempt
            time.sleep(wait)
            continue
        return response
    raise Exception("Превышено максимальное количество попыток")