Для разработчиков

Ошибки

Коды

Мы используем обычные коды ответов 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, 402, 403, 404, 409, 410, 422. Содержит массив errors с детальной информацией об ошибках.
  • OAuthError — для кодов 401 и 403. Содержит поля error и error_description с информацией об ошибке авторизации.

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

  • OAuthError с кодом insufficient_scope, когда у токена нет нужного скоупа (scope) для вызываемого метода. Такой ответ дополнительно содержит заголовок WWW-Authenticate с недостающим скоупом — подробнее в разделе Авторизация.
  • ApiError, когда бизнес-логика запрещает действие (например, недостаточно прав для управления экспортом).
ApiError (400, 402, 403, 404, 409, 410, 422)object
OAuthError (401, 403)object
Код 409 возвращается, когда объект с такими данными уже есть: сотрудник с этим адресом почты, тег с этим названием, закрепление у этого сообщения. В errors[].code приходит already_exists, а в errors[].key — конфликтующее поле: например, email при повторном адресе почты сотрудника. Если определить поле не удалось, key в ошибке не будет.
Ответ 429 Too Many Requests приходит в двух видах. Превышение суточного предела сообщений в чат — обычный ApiError с кодом rate_limit. Превышение лимита на частоту запросов обрабатывается до того, как запрос доходит до метода: тело не JSON, а короткий текст с Content-Type: text/plain. Разбирайте тело 429 только после проверки Content-Type, иначе разбор упадёт. Заголовок Retry-After есть в обоих случаях. Подробнее — на странице Лимиты.