Когда запрос завершается с ошибкой, API возвращает статус status: "error" и объект ошибки с полями error_code (числовой код) и error_message (понятное человеку текстовое сообщение). Распространенные коды ошибок приведены здесь по категориям. Столбец «Повторяемая» (Retryable) указывает, безопасно ли повторять вызов.

Примечание: ответ об отсутствии совпадений не является ошибкой. Если совпадения не найдены, возвращается результат null (в стандартном API) или пустой массив (в enterprise-тарифе) со статусом status: "success". Оставляйте обработку ошибок только для кодов, указанных ниже.

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

API-токен отсутствует, недействительн или отключен. Если вы повторите запрос с тем же токеном, получите ту же ошибку, поэтому ни одна из них не является повторяемой. Сначала исправьте учетные данные и попробуйте снова.

Квота

Токен действителен, но лимит квоты исчерпан. Повторная попытка в том же окне вернет ту же ошибку. Если вы достигли этого лимита, повысьте тарифный план или дождитесь сброса квоты.

Токен действителен, но запрашиваемый эндпоинт, метод или функция для него не включены. Например, вызов эндпоинтов enterprise или streams с токеном, у которого нет такого доступа, приводит к одной из этих ошибок. Эти ошибки не подлежат повтору; сначала необходимо включить эту функцию в аккаунте.

Неверный запрос

Запрос дошел до сервера, но не может быть обработан из-за неправильного или отклоненного параметра. Запрос может быть отправлен повторно после исправления параметра.

Отсутствует файл или параметр

Один из обязательных параметров не был получен, и запрос не может быть повторен, пока вы его не включите. Есть две частые причины для ошибки 700 при POST-запросах. Файлы должны прикрепляться с помощью тела multipart/form-data, поэтому неверный заголовок Content-Type вызывает эту ошибку. Запрос на URL с http:// также может перенаправляться, и тело запроса после перенаправления оказывается пустым; отправляйте его сразу на https://.

Неверный аудиофайл

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

Поток

Достигнуты лимиты подписки на потоки, и запрос не может быть повторен до изменения тарифного плана.

Лимит запросов

Был превышен лимит ежедневных запросов для конкретного потока. Если вы достигли этого лимита, сделайте паузу и повторите попытку после сброса окна лимита, а не повторяйте запрос немедленно.

Серверные и внутренние

Запрос был сформирован правильно, но на сервере что-то пошло не так. Частыми причинами внутренней ошибки (19) являются отключение сервера для планового обслуживания или временный сбой. Внутренние ошибки — это единственные серверные коды, для которых имеет смысл автоматический повтор с экспоненциальной задержкой. Остальные указывают на то, что запрос был заблокирован или метод API неизвестен, и повтору не подлежат.

Как SDK представляют эти ошибки

Каждый официальный SDK считывает error_code из ответа и создает для него типизированное исключение; ни один SDK не возвращает «сырые» блоки ошибок. Имена исключений соответствуют соглашениям каждого языка программирования, а категории одинаковы во всех SDK:

Еще два семейства исключений не имеют серверного кода error_code, поскольку сбой происходит либо до отправки запроса по сети, либо после получения ответа:

Ошибка соединения: Эта ошибка может возникнуть либо из-за того, что запрос так и не дошел до сервера, либо из-за того, что ответ не был получен. Частые причины — сбои DNS и TLS, тайм-ауты и обрывы сокетов. Эта ошибка носит временный характер, поэтому вы можете повторять идемпотентные вызовы с задержкой.
Ошибка сериализации: Возникает, когда тело ответа с кодом 200 OK не удалось разобрать из-за непредвиденной структуры. Эту ошибку нельзя повторить. Проблема в полезной нагрузке (payload).

Каждое типизированное исключение содержит два свойства из ответа: error_code, указывающий на тип возвращенной ошибки, и понятное человеку error_message, описывающее значение кода ошибки. Вы можете использовать error_code, чтобы определить, когда для конкретного кода требуется собственная обработка. Вы также можете перехватить целую категорию в одном блоке catch.

Примечания

Отсутствие совпадений — это не ошибка. result: null (в стандартном API) или пустой массив (в enterprise) означают, что запрос прошел успешно, но совпадений не найдено. Для такого результата не требуется обработка ошибок.
Повторяйте только временные ошибки. Две повторяемые категории — это ошибки соединения и внутренние ошибки сервера (19). Повторяйте их с экспоненциальной задержкой. Категории аутентификации, квот, подписок, неверных запросов, отсутствующих файлов и неверных аудиоданных требуют исправления входных данных или учетной записи. Если вы повторите их, вы получите те же ошибки.
Не повторяйте автоматически тарифицируемые загрузки при неоднозначной ошибке 5xx. После завершения загрузки сервер уже мог выполнить тарифицируемую работу, поэтому повторная попытка после неоднозначной ошибки 5xx может привести к двойному списанию средств. По этой причине SDK не повторяют enterprise-загрузки или загрузки в пользовательский каталог автоматически.
Код 611 требует паузы (backoff), а не немедленного повтора. Если вы сделаете еще один запрос до сброса ежедневного окна, вы упретесь в лимит запросов и получите ошибку 611.
Здесь приведены наиболее распространенные коды из примерно 40 серверных кодов. Любой код, не указанный здесь, обрабатывается SDK как ошибка сервера.
Стратегия повторов
Глоссарий
Документация SDK
Справочник API