Ошибки API

Работая с API Zenky.io вы можете столкнуться с различными ошибками, которые, как правило, возникают при отправке некорректных или при отсутствии необходимых данных. В этом разделе мы описываем список таких ошибок, а так же пути их самостоятельного решения.

Все задокументированные ошибки имеют одинаковый формат ответа - JSON содержит единственное поле error, которое состоит из следующих полей:

Пример ошибочного ответа

{
    "error": {
        "message": "Product was not found.",
        "http_code": "404",
        "error_code": "not_found",
        "meta": {}
    }
}

Ошибки 4XX

Чаще всего ошибки уровня 4XX возникают по причине получения сервером некорректных данных (ошибки валидации), невозможности найти тот или иной ресурс (ошибки 404), а так же при попытке получить доступ к закрытому для вас ресурсу (ошибки 403).

Ошибки доступа

Возникает в том случае, если вы пытаетесь выполнить операцию (в том числе чтения) над ресурсом, доступа к которому вы не имеете. Это может быть связано с тем, что вы пытаетесь создать, отредактировать или удалить сущность, но не предоставляете API токен пользователя, у которого есть такие права.

Причины ошибок

Если вы пытаетесь прочитать список ресурсов или конкретный ресурс (GET-операция), но вместо корректного ответа возвращается 403, это может означать следующее:

  1. Вы пытаетесь прочитать ресурс, который недоступен для неавторизованных пользователей;
  2. Вы пытаетесь прочитать ресурс, который доступен только для сотрудников магазина;
  3. Вы пытаетесь прочитать открытый ресурс, который принадлежит другому магазину;
  4. У авторизованного пользователя нет прав для просмотра защищённого ресурса.

Решение ошибок

  1. Вам необходимо авторизовать пользователя и передавать его API токен на необходимый URL.
  2. Вам необходимо авторизоваться под пользователем, который имеет доступ к управлению магазина.
  3. Ошибка 403 может возникнуть тогда, когда в заголовке X-Store-Id вы передаёте ID одного магазина, но пытаетесь получить доступ к ресурсу (например, товару), который принадлежит другому магазину. В этой ситуации вам нужно либо передать корректный ID магазина в заголовке X-Store-Id, либо передать корректный идентификатор ресурса, принадлежащий магазину, с которым выполняется работа.
  4. У пользователя, имеющего доступ к управлению магазина, нет прав для выполнения конкретной операции.

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

{
    "error": {
        "message": "You have no access to this page.",
        "http_code": "403",
        "error_code": "forbidden",
        "meta": {}
    }
}

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

При создании или обновлении ресурсов мы выполняем валидацию полученных данных. Если какой-либо параметр передан в некорректном формате или имеет некорректное значение, вы получите ответ с кодом 422 Unprocessable Entity и сообщениями что именно пошло не так (в поле errors).

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

{
    "message": "The given data was invalid.",
    "errors": {
        "phone": [
            "Поле Телефон обязательно для заполнения."
        ],
        "code": [
            "Поле code обязательно для заполнения."
        ]
    }
}

Ресурс не найден

Возникают в случае передачи некорректного идентификатора ресурса.

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

{
    "error": {
        "message": "Product was not found",
        "http_code": "404",
        "error_code": "not_found",
        "meta": {}
    }
}

Шлюзы

Шлюзы синхронизации данных могут завершать выполнение ошибками, указанными ниже.

Некорректный идентификатор сущности

Ошибка возникает в том случае, если в качестве идентификатора сущности (поле id) вы передаете значение, отличное от числового или строчного.

В поле error.meta.external_id будет передано значение, которое было отвергнуто шлюзом синхронизации. Имейте в виду, что типом значения этого поля будет тот тип, который вы изначально передавали. Таким образом, если одним из идентификаторов является объект {"id": 1}, то и поле error.meta.external_id будет иметь тип object и значение {"id": 1}.

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

{
    "error": {
        "message": "One of your identifier has non-scalar value.",
        "http_code": "422",
        "error_code": "gate.non_scalar_identifier",
        "meta": {
            "external_id": {"id": 1}
        }
    }
}

Некорректный формат значения сущности

Такие сущности, как характеристики или опции вариантов могут иметь список своих значений. В том случае, если одно из переданных значений имеет некорректную структуру, будет возвращена эта ошибка.

В поле error.meta.value_key будет передан ключ, который хранит некорректное значение. Это означает, что если вы передаёте массив значений, то ключом будет являться индекс такого массива. Если же вы, к примеру, передали объект вида {"1": "Value 1", "2": "Value 2"}, то значением value_key будет являться "1".

В поле error.meta.value будет находиться актуальное значение в том формате, в котором вы нам его передали. Исходя из примера выше, значением будет являться строка "Value 1".

Чтобы избежать этой ошибки передавайте список значений в корректном формате, описанном на документации шлюза характеристик и шлюза опций вариантов.

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

{
    "error": {
        "message": "One of your identifier has non-scalar value.",
        "http_code": "422",
        "error_code": "gate.wrong_value",
        "meta": {
            "value_key": "1",
            "value": "Value 1"
        }
    }
}

Ошибки платформы

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

Мы стараемся определять такие места своими силами, чтобы не допустить их появление в production-среде, однако, некоторые из них всё же просачиваются. Если вы столкнулись с неизвестной ошибкой, формат ответа которой отличается от перечисленных здесь (или же не имеет тела ответа вообще), сообщите, пожалуйста нам на почту [email protected] с темой "API Error".