Ошибки - API WebAsk

Обработка ошибок

API отвечает JSON. Успешный запрос — 200 или 201. Отказ различается кодом HTTP и полем code в теле; по нему и стоит разбирать ответ, не опираясь на текст.

Формат ответа с ошибкой

Отказ с кодом

Так отвечают 400 и 403: признак неуспеха status и машинный код code. Поля error, message, request_id в таком ответе нет.

400, 403

{
  "status": false,
  "code": "access_denied"
}

Нет ключа или ключ недействителен

Стандартный ответ Laravel, без code. Приходит и при отсутствии заголовка Authorization, и при неверном ключе. Ключ бессрочный: отдельного ответа «ключ истёк» нет — ключ перестаёт работать, только если его отозвали в кабинете.

401

{
  "message": "Unauthenticated."
}

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

Стандартный ответ Laravel: общее message и разбор по полям в errors, без code.

422

{
  "message": "The given data was invalid.",
  "errors": {
    "folder_id": ["The folder id field is required."]
  }
}

HTTP коды состояния

Что означает каждый код

Код	Когда приходит
200	Успешный запрос
201	Ресурс создан
400	Запрос корректен, но объекта нет (код сущности: `quiz_not_found` и т.п.) или записать не удалось (код действия: `save_failed` и т.п.)
401	Нет ключа или ключ недействителен; при входе — `invalid_credentials`
403	Действие запрещено: нет доступа, превышен лимит, нет права участника или возможности в тарифе
404	Неверный адрес или метод. Это ответ маршрутизатора, а не «объект не найден»: отсутствующий опрос или ответ приходит как `400` с кодом
422	Запрос не прошёл валидацию, подробности в `errors`
423	Опрос заморожен оплаченной кампанией за респондентов — см. ниже
500	Сбой на нашей стороне (`registration_failed`, `login_failed`). Повторите запрос позже

Коды ошибок

Общие коды

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

HTTP	Код	Описание
400	`email_taken`	Email уже используется
400	`workspace_not_found`	Рабочее пространство не найдено
400	`quiz_not_found`	Опрос не найден
400	`answer_not_found`	Ответ не найден
400	`folder_not_found`	Папка не найдена или не принадлежит воркспейсу
400	`not_found`	Ресурс не найден
400	`not_found_option`	Опция не найдена
401	`user_not_authenticated`	Требуется аутентификация — так написано в описаниях методов; без ключа и с недействительным ключом сервер отвечает телом `{"message": "Unauthenticated."}`, см. выше
401	`invalid_credentials`	Неверные учётные данные при входе
403	`user_deleted`	Пользователь удалён
403	`access_denied`	Нет доступа к ресурсу
403	`access_denied_to_folder`	Нет доступа к папке
403	`quiz_limit_today`	Превышен дневной лимит создания опросов
500	`registration_failed`	Ошибка регистрации
500	`login_failed`	Ошибка входа

Отказы по правам и тарифу

Признак в ответе 403

Пишущие методы работают в тех же границах, что и кабинет: у каждого есть право участника, у части — опция тарифа. Такие отказы приходят с 403 и дополнительным признаком, по которому их различают, не разбирая текст.

Признак	Что значит	Что делать
`blocked_by_access: true`	У участника нет нужного права в этом аккаунте	Право выдаёт владелец аккаунта. Роли и права — `GET /workspace/{workspace_id}/roles`, права одного участника — `GET /workspace/{workspace_id}/members/{memberId}/access`
`blocked_by_tariff: true`	Возможности нет в тарифе аккаунта	Состав тарифа — `GET /workspace/{workspace_id}/tariff`, список тарифов — `/tariff/list`

403 по тарифу

{
  "status": false,
  "code": "blocked_by_tariff",
  "blocked_by_tariff": true
}

Владелец аккаунта проверку права проходит всегда. Право проверяется и на чтение там, где данные чувствительны: например, состояние интеграций требует права integrations. Какое право и какая опция тарифа нужны конкретному методу — сказано в его разделе.

Опрос заморожен кампанией — 423

Правка опроса под оплаченной кампанией за респондентов

Пока по опросу идёт оплаченная кампания, методы, меняющие сам опрос, отвечают 423: POST /quiz/{id}/save, POST /quiz/{id}/publish, POST /quiz/{id}/conditions, POST /quiz/{id}/versions/{versionId}/restore. Респонденты должны пройти ровно то, что оплачено и промодерировано.

423

{
  "status": false,
  "editing_lock": {
    "locked": true,
    "can_edit": false,
    "reason": "...",
    "campaign": { "id": 12, "title": "...", "status": "..." }
  }
}

Состояние заморозки приходит и в GET /quiz/{id} — поле editing_lock (null, когда правкам ничто не мешает). Настройки опроса (POST /quiz/{id}/settings/info), тема, интеграции, скрытые поля и работа с ответами заморозкой не закрыты. До оплаты кампании правки открыты.

Отказ, «пусто» и сбой — разные ответы

Как отличить и стоит ли повторять

Ответ	Что значит	Повтор поможет?
`403`	Доступ есть, но действие запрещено правом или тарифом	Нет — нужен другой уровень прав или тариф
`400` с кодом сущности	Запрос корректен, но объекта нет: `quiz_not_found`, `webhook_not_found`, `password_not_found`, `not_connected`	Нет
`400` с кодом действия	Объект есть, а записать не удалось: `save_failed`, `password_save_failed`, `restore_failed`	Да
`422`	Запрос не прошёл валидацию, подробности в `errors`	После исправления запроса
`200` с полем состояния	Отрицательный результат — это ответ, а не сбой: проверка связи с CRM (`connection_ok`), проверка хранилища (`storage_ok`), тариф без своего хранилища (`available: false`)	Не нужно — ошибки здесь не будет