Ответы и ошибки v2

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

МетодGUIDE Endpointresponses / errors АвторизацияСправка Вход- ВыходHTML

01 / Раздел

Общий принцип

Во v2 сервис старается возвращать короткий и прикладной ответ: либо полезный JSON с результатом, либо ошибку с текстом, который можно сразу разобрать в интеграции.

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

02 / Раздел

Штатные успешные ответы

`POST /api/v2/pages` -> `201 Created`
`POST /api/v2/entity-results` -> `200 OK`
`GET /api/v2/sensei/config` -> `200 OK`
`PATCH /api/v2/sensei/config` -> `200 OK`
`GET /api/v2/sensei/processes` -> `200 OK`
`POST /api/v2/sensei/test-open` -> `200 OK`

03 / Раздел

Основные ошибки

`401 Unauthorized` — отсутствует или неверен `X-Api-Key` / `X-Admin-Token`.
`404 Not Found` — шаблон, страница или организация не найдены.
`415 Unsupported Media Type` — для `POST /api/v2/pages` был отправлен не `multipart/form-data`.
`422 Unprocessable Entity` — в multipart пришли неожиданные поля или данные не прошли валидацию.
`400 Bad Request` — бизнес-ошибка запроса, например невалидный slug, рендер-шаблон с ошибкой или не настроен Sensei.
`402 Payment Required` — нехватка средств для платной операции.
`502 Bad Gateway` — запрос к внешнему Sensei завершился ошибкой.

04 / Раздел

Примеры типовых ошибок

Неверный формат создания страницы

{
  "detail": "Use multipart/form-data with template_id, source_entity_id, data.* and rows.* fields"
}

Неожиданные multipart-поля

{
  "detail": {
    "message": "Unexpected multipart fields",
    "fields": ["foo", "bar"]
  }
}

Ошибка рендера шаблона

{
  "detail": "Template render failed: Missing end of comment tag"
}

Slug занят

{
  "detail": {
    "message": "Page slug is already taken",
    "page_slug": "zinker_offer_9999999"
  }
}

05 / Раздел

Что советовать интегратору

На `401` — проверять ключ и контур доступа.
На `415` — проверять, что отправка страницы идёт именно как `multipart/form-data`.
На `422` — проверять имена полей `data.*` и `rows.*`.
На `400` с текстом рендера — проверять маски в шаблоне.
На `502` — считать ошибку внешней интеграции с Sensei и повторять отдельно.