Правила запросов к API

Лимиты на количество запросов

Существуют лимиты на количество API-запросов в час для всех пользователей клиента. В случае, если лимит на количество запросов будет превышен, на запрос вернется ответ с кодом 429 Too Many Requests и статусом rate_limit_exceeded, следующий запрос можно будет осуществить только в следующем часе. Лимит распространятся на пользователей типа "клиент", “группа внутренних номеров”, "внутренний номер" и является общим для всех пользователей клиента независимо от используемых приложений. Информация о лимите на количество запросов данного типа, количестве оставшихся запросов до исчерпания лимита и времени до сброса счетчика запросов передается в специальных заголовках каждого ответа REST API.

Заголовок

Описание

Заголовок

Описание

X-RateLimit-Limit

Лимит на количество запросов в час на данный ресурс

X-RateLimit-Remaining

Количество оставшихся запросов до исчерпания лимита

X-RateLimit-Reset

Количество секунд до сброса счётчика запросов

Возвращаемые коды и статусы

В данном подразделе представлены коды и статусы, которые возвращает сервер API, а также описание их значений.

Коды успешных запросов

Метод запроса

Код успешного выполнения

Метод запроса

Код успешного выполнения

GET

200

POST

201

PUT

200

DELETE

204

Коды и статусы ошибок запроса

В случае ошибки запроса в ответ возвращается сообщение с кодом 4XX. Дополнительно в ответе может присутствовать поле status, содержащее значение, по которому можно различать ошибки с одинаковым кодом.

Код

Статус

Описание

Код

Статус

Описание

401

 

Пользователь не авторизован. Токен доступа не передается в запросе либо токен доступа просрочен или некорректен (cм. Создание и авторизация приложений)

403

access_denied

Данный пользователь не обладает правом доступа на запрашиваемый ресурс

403

user_blocked

Данный пользователь либо клиент, к которому относится пользователь, заблокирован

403

user_access_type_deny

Недостаточный уровень доступа пользователя

403

app_access_type_deny

Недостаточный для данного ресурса уровень доступа приложения (cм. Создание и авторизация приложений)

404

 

Ресурс не существует

404

client_not_found

Клиент с переданным в пути ID не найден

404

extension_not_found

Внутренний номер с переданным в пути ID не найден

405

 

Ресурс не поддерживает данный метод запроса

413

 

Размер тела запроса больше допустимого (10 МБ)

413

large_file

Размер загружаемого файла больше допустимого для данного ресурса

429

rate_limit_exceeded

Превышен лимит на количество API-запросов (см. Лимиты на количество запросов)

400

limit_exceeded

Превышен лимит на количество ресурсов создаваемого типа (см. Лимиты клиента)

400

input_error

Неверный форма одного из аргументов, передаваемых в теле запроса, либо отсутствие одного из обязательных аргументов

400

wrong_extension_type

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

400

wrong_file

Неверный формат загружаемого файла

400

unresolvable_me

Применение идентификатора ресурса @me для данного пользователя и ресурса невозможно

400

no_records

В запрашиваемом диапазоне дат нет записей для формирования архива записей разговора

400

records_size_too_large

Размер записей разговора запрашиваемом диапазоне дат больше максимально разрешенного для формирования архива. Следует выбрать меньший диапазон дат

400

archive_already_requested

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

400

email_duplicate

Переданный в качестве параметра e-mail адрес уже использован

400

already_exists

Создаваемый ресурс уже существует

5xx

 

Ошибки на стороне сервера. Необходимо проинформировать администратора для принятия соответствующих мер

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

← Структура REST API Методы для работы с ресурсами →