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

Ошибки

Коды

Мы используем обычные коды ответов 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
Что-то пошло не так на сервере Пачки (это редкость). Исключение — 504 у поиска: запрос не уложился по времени, его стоит сузить

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

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

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

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

  • OAuthError, когда отказывает проверка самого токена: код insufficient_scope или role_forbidden из схемы ниже. Ответ с insufficient_scope дополнительно содержит заголовок WWW-Authenticate с недостающим скоупом — подробнее в разделе Авторизация.
  • ApiError, когда отказывает проверка доступа к самому объекту: чат закрыт, правило чата не разрешает действие, роль в пространстве не подходит. Так может ответить любой метод.
ApiError (400, 402, 403, 404, 409, 410, 422, 429, 503, 504)object
OAuthError (401, 403)object
Код 409 возвращается, когда объект с такими данными уже есть: сотрудник с этим адресом почты, закрепление у этого сообщения, черновик в этом чате. В errors[].code приходит already_exists, а в errors[].key — конфликтующее поле: например, email при повторном адресе почты сотрудника. Если определить поле не удалось, в key приходит system. Занятое название тега отвечает 400 с кодом taken, а 409 у тега бывает, только если такой же тег создали одновременно. У черновика вдобавок приходит errors[].payload.draft_id — номер того, который уже лежит в чате, чтобы дописать его методом PUTРедактирование черновика.
Код 504 с errors[].code равным timeout возвращают методы поиска и GETСписок сотрудников с параметром query, когда запрос не уложился по времени. Такой запрос стоит сузить: повтор того же запроса, скорее всего, снова не уложится.
Ответ 429 Too Many Requests — обычный ApiError с кодом rate_limit, а в заголовке Retry-After приходит, через сколько секунд можно повторить запрос. Так отвечают и лимиты на частоту запросов, и суточный предел сообщений в чат. Подробнее — на странице Лимиты.