Основы API
Методы API

Ошибки и лимиты

Коды

Мы используем обычные коды ответов HTTP для обозначения результата выполнения запроса.

Коды группы 2** указывают на успех. Коды группы 3** указывают на перенаправление (например, при скачивании файла). Коды группы 4** указывают на ошибку запроса, который не удался с учетом предоставленной информации (например, обязательный параметр был пропущен, несуществующий идентификатор и др.). Коды группы 5** указывают на ошибки на серверах Пачки (они редки).

Коды ответов HTTP
200OK
Запрос отработал как положено, без ошибок
201Created
Запрос отработал успешно, сущность создана
204No Content
Запрос отработал успешно, тело ответа отсутствует (например, при удалении ресурса)
301Moved Permanently
Запрошенный ресурс был на постоянной основе перемещён в новое месторасположение (такой ответ вы можете получить если выполните запрос по протоколу HTTP, а не по HTTPS)
302Found
Перенаправление на другой URL (например, при скачивании файла экспорта — в заголовке Location будет временная ссылка на файл)
400Bad Request
Неприемлемый запрос (часто из-за отсутствия обязательного параметра)
401Unauthorized
Предоставлен недействительный токен доступа
402Payment Required
Параметры действительны, но запрос не выполнен
403Forbidden
Предоставленный токен доступа не имеет разрешений на выполнение запроса
404Not Found
Запрашиваемый ресурс не существует
409Conflict
Запрос конфликтует с другим запросом (возможно, из-за использования того же идемпотентного ключа)
410Gone
Ресурс больше не доступен (например, истёк срок действия идентификатора события)
422Unprocessable Entity
С запросом все хорошо, но правила сервиса не позволяют его обработать (например, при попытке создания контакта с уже существующим номером телефона в базе)
429Too Many Requests
Слишком много запросов слишком быстро попадают в API
500, 502, 503, 504Server Errors
Что-то пошло не так на сервере Пачки (это редкость)

Пояснения ошибки

В зависимости от типа ошибки вы получите в теле ответа одну из следующих структур:

  • ApiError — для кодов 400, 403, 404, 409, 410, 422. Содержит массив errors с детальной информацией об ошибках.
  • OAuthError — для кодов 401 и 403. Содержит поля error и error_description с информацией об ошибке авторизации.

Код 403 может вернуть обе структуры:

  • OAuthError с кодом insufficient_scope, когда у токена нет нужного скоупа (scope) для вызываемого метода.
  • ApiError, когда бизнес-логика запрещает действие (например, недостаточно прав для управления экспортом).
ApiError (400, 403, 404, 409, 410, 422)object
OAuthError (401, 403)object

Лимиты

Мы следим за стабильностью API, поэтому есть лимиты на запросы (rate limiting). Они гибкие, зависят от нагрузки, но мы сделали их комфортными — должно хватить для любых ваших задач.

Входящие вебхуки
Лимит привязан к идентификатору вебхука в пути.
Например, для /webhooks/user123 считаем по user123
Лимит
~4 запроса
Период
1 секунда

Если за секунду отправите больше 2 запросов на один идентификатор, лишние получат 429 Too Many Requests. В заголовке Retry-After мы укажем, через сколько секунд можно попробовать снова.

API

Отправка, изменение и удаление сообщений
Считаем по токену авторизации (заголовок HTTP_AUTHORIZATION). Один токен — один лимит. Запросы учитываются по каждому чату отдельно. Дополнительно, допускаются короткие ускорения выше указанного лимита отправки сообщений: до 30 запросов в секунду на протяжении 5 секунд в каждый чат.
Лимит
~4 запроса
Период
1 секунда
Сущность
chat_id
Получение сообщений
Считаем по токену авторизации (заголовок HTTP_AUTHORIZATION). Один токен — один лимит.
Лимит
~10 запросов
Период
1 секунда
Остальные методы API
Считаем по токену авторизации (заголовок HTTP_AUTHORIZATION). Один токен — один лимит.
Лимит
~50 запросов
Период
1 секунда

Если за секунду будет больше указанных запросов с одним токеном, API вернёт 429 Too Many Requests. В заголовке Retry-After мы укажем, через сколько секунд можно попробовать снова.

  • Лимиты гибкие: они ориентировочные и могут меняться, чтобы всё работало гладко;
  • Должно хватать на всё: мы настроили их так, чтобы вам было комфортно в любых сценариях;
  • Если упёрлись в лимит: при ошибке 429 смотрите заголовок Retry-After — он подскажет, через сколько секунд повторить запрос (или используйте экспоненциальный backoff, если хотите перестраховаться).