Главная → Блог → Ошибки API распознавания речи и что они означают

Ошибки API распознавания речи и что они означают

Опубликовано 2026-08-20 · 5 мин чтения

Интеграция ломается редко, но всегда не вовремя. Хорошая новость: у ошибок распознавания короткий список причин, и почти каждая чинится за минуту. Разберём коды по порядку и заодно посмотрим, какие из них стоит повторять автоматически.

Таблица кодов

Код	Что произошло	Что делать
401	Ключ неверный, отозван или не дошёл	Проверить заголовок Authorization и сам ключ
400	Файл пуст, повреждён или не распознан как аудио	Открыть файл плеером, проверить кодек
413	Файл больше предельного размера	Сжать в opus или разрезать на части
429	Превышен лимит запросов или кончился баланс	Снизить частоту, пополнить баланс
502	Сервис распознавания временно недоступен	Повторить через паузу

Формат ответа совпадает со стандартным: объект error с полями message и type, поэтому типизированные исключения в SDK работают как обычно.

401: чаще всего дело в заголовке

Три типовые причины, в порядке частоты:

Ключ вставлен с лишним пробелом или переносом строки — особенно если копировали из письма.
Забыто слово Bearer в заголовке: нужно Authorization: Bearer ваш_ключ.
Ключ из тестового окружения ушёл в боевое или наоборот.

Проверить ключ быстрее всего из терминала — если curl проходит, дело в коде, а не в доступе.

429: два разных случая

Один и тот же код приходит и когда вы стучитесь слишком часто, и когда закончились оплаченные минуты. Различить их можно по тексту сообщения. Первый случай лечится очередью с ограничением параллельности, второй — пополнением баланса.

Полезная привычка: смотреть на остаток в личном кабинете и настроить уведомление заранее, а не узнавать об исчерпании из логов боевого сервиса.

Как повторять запросы

Повторять имеет смысл только временные ошибки: 429, 502 и сетевые обрывы. Ошибки 400, 401 и 413 при повторе вернут ровно то же самое — их надо чинить, а не долбить.

import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(base_url="https://voicesscribe.com/v1", api_key="ваш ключ", max_retries=0)

def transcribe(path, tries=4):
    delay = 2
    for attempt in range(tries):
        try:
            with open(path, "rb") as f:
                return client.audio.transcriptions.create(model="whisper-1", file=f).text
        except APIStatusError as e:
            if e.status_code not in (429, 500, 502, 503):
                raise
        except APIConnectionError:
            pass
        time.sleep(delay)
        delay *= 2
    raise RuntimeError("не удалось расшифровать " + str(path))

Удвоение паузы важнее числа попыток: оно даёт сервису шанс разгрузиться, а вам — не упереться в тот же лимит через секунду.

Попробуйте на своих записях. Регистрация занимает минуту, бесплатных минут хватает, чтобы оценить качество.

Получить ключ бесплатно

Частые вопросы

Списываются ли минуты при ошибке?

Нет. Тарифицируются только успешно обработанные запросы, ошибки минут не расходуют.

Почему приходит 400 на файл, который открывается плеером?

Чаще всего это переименованный файл: расширение mp3, а внутри другой контейнер. Проверьте формат командой ffprobe и при необходимости перекодируйте.

Как понять, что 429 — про баланс, а не про частоту?

По тексту сообщения в теле ответа. Остаток и историю списаний всегда видно в личном кабинете.

Стоит ли включать встроенные повторы SDK?

Обычно нет: своя логика повторов надёжнее, потому что вы сами решаете, какие коды повторять и с какими паузами.