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

Ошибки

Коды

Мы используем обычные коды ответов 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) для вызываемого метода.
  • ApiError, когда бизнес-логика запрещает действие (например, недостаточно прав для управления экспортом).
ApiError (400, 402, 403, 404, 409, 410, 422)object
OAuthError (401, 403)object
Про ответ 429 Too Many Requests, заголовок Retry-After и готовые примеры экспоненциального backoff — на отдельной странице Лимиты.