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

Коды

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

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

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

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

Вместе с кодом 400 вы получите в теле ответа массив errors.

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

key	string	Ключ параметра, в котором произошла ошибка
value	string	Значение ключа, которое вызвало ошибку
message	string	Ошибка текстом, который вы можете вывести пользователю
code	string	Внутренний код ошибки (коды ошибок представлены в описании каждого метода)
payload	object	Объект, который предоставляет любую дополнительную информацию (возможные дополнения представлены в описании каждого метода)

Лимиты

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

Входящие вебхуки

Как работает

Лимит привязан к идентификатору вебхука в пути
Например, для /webhooks/user123 считаем по user123

Лимит

~4 запроса

Период

1 секунда

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

API

Как работает

Считаем по токену авторизации (заголовок HTTP_AUTHORIZATION)
Один токен — один лимит

Отправка, изменение и удаление сообщений - POST /messages, PUT /messages/{id}, DELETE /messages/{id}

Лимит

~4 запроса

Период

1 секунда

Сущность

chat_id

POST, PUT и DELETE запросы ручки /messages учитывается по каждому чату отдельно. Дополнительно, допускаются короткие ускорения выше указанного лимита отправки сообщений: до 30 запросов в секунду на протяжении 5 секунд в каждый чат.

Получение сообщений - GET /messages, GET /messages/{id}

Лимит

~10 запросов

Период

1 секунда

Остальные методы API

Лимит

~50 запросов

Период

1 секунда

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

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