Правила запросов к API
Для уменьшения нагрузки на сеть в обязательном порядке необходимо использовать заголовок сжатия “Accept-Encoding: gzip”
Лимиты на количество запросов
Существуют лимиты на количество API-запросов в час для всех приложений клиента. В случае, если лимит на количество запросов будет превышен, на запрос вернется ответ с кодом 429 Too Many Requests и статусом rate_limit_exceeded, следующий запрос можно будет осуществить только в следующем часе.
Есть два типа лимитов:
Общий лимит - распространяется на все приложения клиента.
Персональный лимит приложения (опциональный параметр)
Информация о количестве оставшихся запросов до исчерпания лимита и времени до сброса счетчика запросов передается в специальных заголовках каждого ответа REST API.
Заголовок | Описание |
|---|---|
X-RateLimit-Limit | Лимит на количество запросов в час на данный ресурс |
X-RateLimit-Remaining | Количество оставшихся запросов до исчерпания лимита |
X-RateLimit-Reset | Количество секунд до сброса счётчика запросов |
Также существует лимиты запросов на ресурсы /oauth и /login:
20 запросов в секунду
6 одновременных соединений
Пример распределения лимита на количество запросов по приложениям клиента для общего лимита
Клиент имеет 4 приложения.
1 приложение имеет лимит 100
2 приложение имеет лимит 200
3 приложение имеет лимит 300
4 приложение имеет лимит 1000
1 приложение в текущем часе сгенерировало 55 запросов
2 приложение в текущем часе сгенерировало 5 запросов
3 приложение в текущем часе сгенерировало 35 запросов
4 приложение в текущем часе сгенерировало 5 запросов
Общее количество запросов по 4 приложениям = 100
приложение 1 в текущем часе при следующем запросе получит 429 Too Many Requests и статусом rate_limit_exceeded, т.к. общий счетчик запросов составляет 100, что является лимитом для приложения 1
Приложение 2 получит rate_limit_exceeded, когда общий счетчик запросов составит 200, Приложение 3 получит rate_limit_exceeded, когда общий счетчик составит 300
Приложение 4 не получит Too Many Requests, пока общий счетчик приложения клиента не достигнет значения 1000
Если установлен Персональный лимит приложения, то приложение инкрементит свой счетчик и общий счетчик по всем приложениям, но блокируется только в том случае, если его личные запросы достигли персональный лимит.
Возвращаемые коды и статусы
В данном подразделе представлены коды и статусы, которые возвращает сервер API, а также описание их значений.
Коды успешных запросов
Метод запроса | Код успешного выполнения |
|---|---|
GET | 200 |
POST | 201 |
PUT | 200 |
DELETE | 204 |
Коды и статусы ошибок запроса
В случае ошибки запроса в ответ возвращается сообщение с кодом 4XX. Дополнительно в ответе может присутствовать поле status, содержащее значение, по которому можно различать ошибки с одинаковым кодом.
Код | Статус | Описание |
|---|---|---|
401 |
| Пользователь не авторизован. Токен доступа не передается в запросе либо токен доступа просрочен или некорректен (cм. Создание и авторизация приложений) |
401 | invalid_grant | Может возникнуть при регенерации токена через refresh_token. Приложению необходимо повторно осуществить авторизацию |
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 |
| Ошибки на стороне сервера. Необходимо проинформировать администратора для принятия соответствующих мер |
Более одного запроса на одно действие совершать не нужно. Если при предыдущей попытке совершить запрос была получена ошибка, значит, нужно предпринять какие-либо действия и только затем повторить запрос. Повторная отправка запроса должна быть инициирована только пользователем (при инициации запроса пользователем) или через определенное время (при автоматических запросах), но ни в коем случае не в бесконечном цикле. Об ошибке пользователь должен узнать в соответствующем уведомлении.