Ошибки BAAS API

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

• Production — api.baas.kvell.group
• Stage — api.baas.stage.kvell.group

Формат ответа

BAAS API возвращает ошибки в массиве errors. Для ошибки валидации дополнительно возвращается поле field.

Ошибка валидацииДругая ошибка

Пример ошибки валидации

{
  "errors": [
    {
      "code": 0,
      "message": "Input should be less than or equal to 100",
      "field": "size"
    }
  ]
}

Пример ошибки авторизации

{
  "errors": [
    {
      "code": 11,
      "message": "Неверная подпись"
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
errors	array	Список ошибок. Для одного запроса может быть возвращено несколько ошибок валидации.
∟ code	integer	Код ошибки BAAS API.
∟ message	string	Описание ошибки.
∟ field	string	Поле с некорректным значением. Возвращается только для ошибок валидации.

Список ошибок

Коды с фиксированным HTTP-статусом сгруппированы по статусам и не повторяются между таблицами. Коды 0 и 4 описаны отдельно, поскольку их HTTP-статус зависит от причины ошибки.

HTTP 400 — ошибка запроса

Код	Сообщение	Что означает и что делать
2	Некорректный JSON	Проверьте синтаксис JSON, типы значений и заголовок Content-Type, затем повторите запрос.
3	Некорректные данные	Проверьте параметры по документации метода и повторите запрос после исправления.
32	Чек нельзя аннулировать	Проверьте состояние чека. Аннулировать можно только чек в статусе, допустимом для аннулирования.
35	Чек ещё нельзя аннулировать, попробуйте позже	Чек в статусе await_confirm, его идентификатор в системе регистрации доходов пока не получен. Повторите запрос позже.
41	Не найден профиль выпуска карт	Обратитесь к менеджеру KVELL для настройки профиля выпуска карт.
51	Сумма заказа не соответствует сумме акта	Проверьте сумму заказа и итоговую сумму позиций акта, затем повторите запрос после исправления.

HTTP 401 — ошибка авторизации

Код	Сообщение	Что означает и что делать
10	Неверный api-key	Проверьте API-ключ и контур запроса.
11	Неверная подпись	Проверьте алгоритм подписи для вызываемого метода, порядок значений, secret_key и подписываемые данные.

HTTP 403 — доступ запрещён

Код	Сообщение	Что означает и что делать
12	Доступ запрещен	Убедитесь, что магазин активен и ему разрешён доступ к BAAS API.
42	Доступ запрещён	У магазина нет доступа к запрошенному сервису. Проверьте подключение услуги у менеджера KVELL.

HTTP 404 — данные не найдены

Код	Сообщение	Что означает и что делать
20	Магазин не найден	Проверьте X-Api-Key и выбранный контур: Production или Stage.
21	Мерчант не найден	Проверьте идентификатор мерчанта и настройки магазина.
30	Чек не найден	Проверьте идентификатор чека и магазин, от имени которого выполняется запрос.
31	Клиент не найден	Проверьте идентификатор клиента и магазин, от имени которого выполняется запрос.
40	Заявка не найдена	Проверьте идентификатор заявки на выпуск карты.
43	Профиль для СБЕР не найден	Обратитесь к менеджеру KVELL для настройки Sber-профиля.
44	Пользователь не найден	Проверьте идентификатор пользователя и магазин, от имени которого выполняется запрос.
50	Заказ не найден	Проверьте идентификатор заказа и магазин, от имени которого выполняется запрос.

HTTP 422 — ошибка валидации

Код	Сообщение	Что означает и что делать
5	Необходимо заполнить хотя бы одно поле	Передайте хотя бы один из параметров, перечисленных в документации метода.
6	Должно быть передано одно из полей: transactions или orders	Передайте ровно одно поле: transactions или orders. Не передавайте их одновременно.

Ошибки формата отдельных полей также возвращаются с HTTP 422, но используют код 0, описанный в разделе «Коды с переменным HTTP-статусом».

HTTP 500 — внутренняя ошибка

Код	Сообщение	Что означает и что делать
1	Неизвестная ошибка	Произошла необработанная техническая ошибка. Используйте рекомендации из раздела «Технические ошибки и отсутствие ответа».

HTTP 503 — сервис недоступен

Код	Сообщение	Что означает и что делать
45	СМЭВ не доступен	Сервис СМЭВ временно недоступен. Повторите запрос позднее; при повторении ошибки обратитесь в поддержку.

Коды с переменным HTTP-статусом

Код	HTTP-статус	Сообщение	Что означает и что делать
0	Зависит от ошибки	Определяется причиной ошибки	Для ошибки валидации исправьте параметр из field. Если field отсутствует, проверьте URL, HTTP-метод и сообщение ответа.
4	Статус зависимого сервиса	Зависит от ответа сервиса	Зависимый сервис вернул ошибку. Обработка описана в разделе «Ошибка зависимого сервиса».

Ошибки валидации

Для ошибок формата заголовков, query-параметров, path-параметров и тела запроса BAAS API возвращает HTTP 422 и код 0. Поле field содержит имя некорректного параметра, а message — причину ошибки.

В одном ответе может быть несколько элементов errors. Исправьте все перечисленные поля перед повторным запросом.

Пример нескольких ошибок валидации

{
  "errors": [
    {
      "code": 0,
      "message": "Field required",
      "field": "x-api-key"
    },
    {
      "code": 0,
      "message": "Field required",
      "field": "x-signature"
    }
  ]
}

Ошибка зависимого сервиса

Код 4 означает, что зависимый сервис вернул ошибку. BAAS API сохраняет его HTTP-статус, а в message передаёт извлечённое описание причины. Поэтому код 4 может встречаться как в ответах 4XX, так и в 5XX.

Порядок обработки зависит от HTTP-статуса:

1. Для 4XX проверьте параметры запроса и описание в message. Не повторяйте запрос без исправления причины.
2. Для 5XX используйте правила обработки технических ошибок для вызываемого метода.
3. Если причина непонятна или ошибка повторяется, обратитесь в поддержку и передайте X-Request-ID, HTTP-статус, code и message.

Технические ошибки и отсутствие ответа

Порядок действий зависит от типа метода:

• для read-only-метода безопасно повторите запрос с теми же параметрами; если подпись включает X-Request-ID, сформируйте новый идентификатор и пересчитайте подпись;
• для метода, который создаёт или изменяет данные, не выполняйте автоматический повтор, пока не проверите рекомендации на странице метода и не установите результат исходного запроса;
• если ответ не получен из-за таймаута или разрыва соединения, тела с errors у клиента не будет.

При повторяющихся технических ошибках обратитесь в поддержку и передайте URL метода, время запроса, X-Request-ID и полученный ответ, если он есть.